LightAgent: Instructions file for Codex

LightAgent 项目协作指南

本文件面向在本仓库内工作的 AI Agent 与开发者。目标是先理解项目边界，再用最小改动完成需求，并保留可验证、可回退的交付路径。

项目概览

LightAgent 是一个以 Python 为主的多渠道 Agent Harness 项目，包含：

• 后端运行入口：app.py
• 配置中心：config.py、config-template.json
• 消息渠道层：channel/
• 模型、语音、翻译路由：bridge/、models/、voice/、translate/
• Agent 核心协议、工具、技能、记忆、知识库：agent/
• 插件系统：plugins/
• CLI：cli/
• 历史桌面端归档：desktop/（停止维护，不参与构建发布）
• 文档站内容：docs/
• 回归测试：tests/

项目核心数据流：

1. app.py 加载配置并启动 ChannelManager。
2. channel/channel_factory.py 根据 channel_type 创建 Web、IM 或终端渠道。
3. 渠道把消息包装为 bridge.context.Context。
4. bridge/bridge.py 根据配置选择聊天模型、语音、翻译或 Agent 模式。
5. Agent 模式通过 bridge/agent_bridge.py 进入 agent/，按工具、技能、记忆与知识库上下文执行任务。
6. 回复通过原渠道发送回用户。

主要目录职责

• agent/protocol/：Agent 执行协议、流式执行、动作与结果模型。
• agent/tools/：内置工具实现。新增工具时优先继承 BaseTool，并确认 agent/tools/__init__.py 与 ToolManager 加载路径。
• agent/tools/mcp/：MCP 客户端与动态工具注册。修改时注意并发加载、热更新和子进程生命周期。
• agent/skills/：技能加载、过滤、启停配置与 prompt 格式化。内置技能在根目录 skills/，用户技能通常在 workspace 的 skills/。
• agent/memory/、agent/knowledge/：长期记忆、向量/关键词索引、知识库服务。
• bridge/：模型、语音、翻译、Agent 模式的统一路由层。改动这里会影响所有渠道。
• channel/：不同平台渠道。公共逻辑在 channel/channel.py、channel/chat_channel.py；新增渠道需接入 channel/channel_factory.py。
• channel/wechat_group/：个人微信群通道实现。Python 层负责 LightAgent 渠道适配、配置读取、上下文包装和回复发送；sidecar/ 下的 Node.js Wechaty 进程负责扫码登录、群列表、群消息事件和微信侧真实发送。
• models/：不同 LLM Provider 的 Bot 与 Session。新增 Provider 要同步 common/const.py、models/bot_factory.py 和相关配置/文档。
• plugins/：聊天命令插件与插件管理器。不要把 Agent 工具和插件混为一类。
• voice/、translate/：ASR/TTS 与翻译 Provider。
• desktop/：已停止维护的 Electron 历史源码归档，不再开发、修复、构建或发布；Python 后端 app.py 不属于桌面端，继续作为项目主入口维护。
• docs/：英文、中文。日文文档（docs/ja/）已停止维护，不再更新。涉及用户可见能力变更时，只需更新英文和中文对应文档。
• tests/：unittest 风格回归测试，很多测试通过 stub/mocking 避免真实网络和外部服务。

本地运行与验证

默认在 Windows PowerShell 中工作。不要使用 && 串联命令。

访问 GitHub 时如果直连请求超时或不稳定，可以使用本地代理 http://192.168.3.5:1082 重试；仅在网络访问场景使用该代理，不要把代理地址写入项目运行配置或代码默认值。

整理或创建 GitHub issue 时，一律提交到 yideng966/LightAgent 项目；标题和正文描述应使用简体中文，避免默认写英文；提交时必须注明合适的 label，至少明确是 bug、功能需求、文档或其他类型；不要默认使用当前 remote、fork 或其他仓库；docs\images目录不要提交开发过程截图。