Imported from ifquant/xagents (
AGENTS.md). Install upstream withnpx skills add ifquant/xagents. Copyright stays with the author.
AGENTS.md
Scope: /Users/dev/workspace2/agents_research/xagents
本文件补充父级工作区规则。进入本目录工作时，除了遵守上层 AGENTS.md，还必须遵守这里的本地约定。
项目概览
xagents 是你的一个 agents 实现仓，目标不是只做 coding agent，而是构建一个可扩展的多 agents 平台。
当前已确认的仓库事实：
- 这是一个独立 git 仓库，当前分支为
main - 当前已经是 Rust workspace，包含
crates/下 7 个 crate - 当前已经有稳定的 README、profiles、notes、CI workflow、commit tutorials 和 Cargo 验证门
- 该压缩包内包含一个名为
claude-code3/的源码树 claude-code-tangtao.tar.gz是保留的原始参考归档，不是当前实现源码
当前明确的产品方向：
xagents要实现的是多 agents 系统，而不是单一编码助手- 系统需要支持通过外挂不同“外脑”能力，形成面向不同领域的 agents
- coding agent 只是其中一种 agent 形态，不应成为整体架构的唯一中心
- 设计时会参考以下实现或代码库：
/Users/dev/workspace2/agents_research/claude-code-best/Users/dev/workspace2/agents_research/claw-code/Users/dev/workspace2/agents_research/claw/openclaw
因此，本仓库的主要工作模式是：
- 记录并推进
xagents的真实 Rust workspace 实现 - 管理原始归档文件和参考材料
- 记录研究、解包、对比和架构决策流程
- 在明确目标 crate / 文档目录后，再开展代码分析或改动
不要把当前目录误判为“只有归档、没有产品目标”的临时目录。当前仓库已经有可运行的 Rust workspace、CLI、session/runtime/brains/tools/core/protocol 分层和 CI 质量门；但它仍处于平台底座与策略快速演进阶段，真实 model / knowledge / action adapters、daemon/RPC、完整 TUI 等还不是成熟完成态。
适用范围
本文件适用于：
/Users/dev/workspace2/agents_research/xagents- 未来在该目录下新增的研究说明、解包结果、比较笔记、教程文件
如果后续将压缩包解压到子目录，且该子目录存在自己的 AGENTS.md，必须先读子目录规则，子目录规则优先。
目录导航
当前已存在内容：
Cargo.toml/Cargo.lock: Rust workspace 根清单crates/: 当前实现源码profiles/: 默认 agent profile 配置notes/: 研究记录和架构文档claude-code-tangtao.tar.gz: 原始归档文件，内含claude-code3/tutorials/commit/: 每次提交配套的中文教程.github/workflows/ci.yml: GitHub Actions 质量门
当前 crate 结构：
crates/core: IDs、events、profiles、planner/task/session shared typescrates/runtime: coordinator / worker / planner routing / execution orchestrationcrates/brains: model / knowledge / action provider traits and built-in planner policycrates/session: JSONL event log、snapshot、planning trace query/replaycrates/tools: tool protocol, built-in shell/filesystem/search tools, and a reserved web stubcrates/protocol: schema export bundlecrates/cli:xagents-cli
未来若需要解包参考归档，推荐目录：
extracted/: 解压后的源码目录，避免直接把大量解包文件散落在仓库根目录
如果用户没有明确指定目录，默认优先基于当前 Rust workspace 工作，不要擅自解包 claude-code-tangtao.tar.gz 或把参考源码混进实现树。
常用命令
在当前仓库中，优先使用这些低风险命令确认事实：
git status --short --branch
ls -la
cargo metadata --no-deps --format-version 1
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
cargo doc --no-deps --all-features
cargo package --workspace --locked归档检查只在任务涉及原始参考包时运行：
tar -tzf claude-code-tangtao.tar.gz | head -n 80只有在任务明确要求解包或分析归档内源码时，才使用解压命令。推荐解压到单独目录：
mkdir -p extracted
tar -xzf claude-code-tangtao.tar.gz -C extracted解压后若需要继续工作，先检查：
find extracted -name AGENTS.md -print开发原则
- 先确认目标：先判断任务是在“归档文件、研究文档、还是解包后的源码目录”中执行，再动手。
- 保持可追溯：任何解包、重命名、整理、删改归档内容的动作，都要能在提交说明和教程中说清楚原因。
- 保留原件：默认不要覆盖、替换、重打包或删除
claude-code-tangtao.tar.gz，除非用户明确要求。 - 研究和源码分离：研究文档、笔记、教程与解包源码尽量分目录管理，避免把分析产物混进源码树。
- 小步提交：每次只处理一个清晰目标，例如“新增仓库协作规则”“补充解包流程说明”“整理第一次结构扫描结果”。
- 架构优先：任何实现都要优先服务于“多 agents + 外脑扩展”目标，而不是只模仿单一 coding CLI。
- 参考而不照搬：可以借鉴
claude-code-best、claw-code、openclaw的结构、调度、工具接入、会话管理与工程化实践，但不要默认复制任何一个项目的单体边界。 - 领域 agent 优先考虑可插拔：新增能力时，优先设计成可组合的 agent 能力模块、外脑适配层或编排节点，而不是写死在某个 coding flow 里。
代码约定
- 当前正式源码是 Rust workspace，默认使用
cargo fmt格式化。 - 对行为层改动，优先补对应 crate 的 targeted tests，再跑 workspace 级质量门。
- 对跨 crate public type / manifest / package 边界改动，必须至少跑
cargo metadata --no-deps --format-version 1和cargo package --workspace --locked。 - 对 trace/query/session 可见性改动，优先补
crates/session的 query/replay tests，并同步 README / CLI 文档。 - 对 runtime / brains resumed confirmation policy 改动，保持 typed fields 优先，不要回退到 payload string parsing。
- 对性能敏感路径，不要只提供 allocation-heavy convenience API；如果新增高层易用接口，保留或设计低开销入口，例如借用参数、调用方提供 buffer、或可直接消费 typed artifact 的路径。
- 如果后续进入解包后的参考项目，必须先识别该子项目自己的构建工具和规则，不要把当前 workspace 约定直接套过去。
应用领域硬约束
- 本仓库的目标是“多 agents 平台 + 领域 agent 扩展”，不是单一 coding assistant。
- 任何新增模块都应回答：它是在增强 agent 编排能力，还是在增强某种外脑接入能力，还是在实现某个具体领域 agent。
- 未经确认，不要批量解压多个版本归档，不要创建含糊的散乱目录名。
- 涉及压缩包内容结构分析时，优先先用
tar -tzf查看，不要一上来全量解包。 - 如果要比较归档内源码与外部仓库，比较结果应写到研究文档中，不要直接改原始归档文件。
- 不要把“工具调用成功”误当成“领域 agent 已完成设计”。领域 agent 至少要定义清楚目标用户、外脑依赖、工具权限、输入输出和失败回退策略。
- 不要把所有能力都塞进一个超级 agent。优先明确 agent 分工、编排关系和能力边界。
- 参考
openclaw时，重点学习其工程组织、通道/扩展边界、配置和运维约束；参考claude-code-best与claw-code时，重点学习其 agent harness、工具组织、工作流设计和重构取舍。
测试与验收
当前仓库的默认质量门与 CI 保持一致：
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
cargo doc --no-deps --all-features
cargo package --workspace --locked最低成本验证按改动范围裁剪：
- 单 crate 行为改动：先跑对应
cargo test -p <crate> --lib或更窄测试，再按风险决定是否跑全门。 - CLI / README / tutorial 文档改动：至少跑
cargo fmt --check，并检查相关命令、Markdown code fence 和教程编号连续性。 - manifest / lockfile / package 改动：必须跑
cargo metadata --no-deps --format-version 1、cargo package --workspace --locked，以及相关测试。 - 归档类改动：至少重新执行一次
tar -tzf claude-code-tangtao.tar.gz | head -n 80或等价命令，确认归档可读。 - 若新增架构或设计文档：检查是否清楚说明多 agents 分层、外脑边界和参考来源。
禁止事项
- 不要删除、覆盖或重写
claude-code-tangtao.tar.gz，除非用户明确授权 - 不要在未确认目标目录时直接修改解包后的源码
- 不要把
.git/、压缩包内部自带的.git/目录，或大批量解包产物误提交进不该提交的位置 - 不要引入
npm test、pytest等非本仓真实工具链命令作为默认验收；当前默认工具链是 Cargo - 不要跨到父工作区其他项目目录做改动，除非任务明确要求
- 不要把
claude-code-best、claw-code、openclaw中的专用实现细节原样搬进xagents，除非本次任务明确要求并说明兼容性后果 - 不要把
xagents写死成只服务编码场景的 agent 框架
需要先确认的情况
遇到以下情况，先确认再继续：
- 要不要真正解压
claude-code-tangtao.tar.gz - 解压目录是否固定为
extracted/，还是用户已有既定目录 - 是否允许提交解压后的大体积源码文件
- 是否需要保留压缩包内部原始目录名
claude-code3/ - 是否要把解包结果当成新的子仓库、镜像仓或仅作临时研究材料
- 新能力是通用平台能力，还是某个领域 agent 的专属能力
- 新增的“外脑”属于工具适配、知识接入、模型路由，还是完整子系统
- 是否需要保持与参考实现的接口或行为兼容
提交 / PR 要求
非琐碎提交必须使用高信息量提交信息。提交正文至少写清：
Why:为什么要做这次改动Changes:改了哪些文件和结构Verification:用了什么命令或检查方式验证Not included:明确这次故意没处理什么
提交主题禁止使用空泛词，如：
fixupdatecleanupmisc
除非改动确实极小且没有更具体的描述空间。
如果本次只覆盖部分范围，提交信息必须明确写出已覆盖范围与未覆盖范围。
自动提交规则
默认启用自动提交工作流。只要一个清晰功能片段已经完成，且满足以下条件，AI 就应直接提交，不必等待用户再次提醒：
- 改动边界清楚，只解决一个明确目标
- 已完成本次应有的最低成本验证
- 已写好对应的
tutorials/commit/NNNN-*.md - 提交信息符合本文件的高信息量要求
不要把多个无关目标塞进一次自动提交。一个提交只对应一个明确主题。
对本仓库来说，典型“可自动提交的功能片段”包括：
- 新增或修订
AGENTS.md - 增加一次归档检查/解包流程文档
- 新增一篇结构研究笔记
- 整理一次明确范围的目录规范
- 定义一个明确的 agent 抽象或外脑接入边界
- 增加一个单独的领域 agent 设计文档或实现骨架
- 完成一个明确 crate 内行为修复并补对应测试
- 完成一个明确 CI / package / manifest / README 收口
Commit 教程要求
每次非琐碎提交，必须新增一篇教程文件，路径格式：
tutorials/commit/NNNN-short-topic.md
规则如下：
- 编号使用四位数字，自
0001开始递增 - 不要跳号，不要复用旧编号
- 默认使用中文写给中文协作者和新手读者
- 命令、路径、API 名、代码符号保留原文，避免翻译后不可用
- 教程不是 diff 摘抄，而是帮助后来者理解“为什么这样做”
- 每篇教程默认包含 1 到 2 条来自真实工作过程的入门补充知识，例如：
- 一个命令行或归档处理知识点
- 一个目录组织或研究记录方法
- 一个让 AI 协作更稳定的提示方式
推荐章节：
背景主要目标改动概览关键知识补充知识验证未覆盖项
参考资料
- 父级规则：
/Users/dev/workspace2/agents_research/AGENTS.md - 当前归档：
/Users/dev/workspace2/agents_research/xagents/claude-code-tangtao.tar.gz - 当前 CI：
/Users/dev/workspace2/agents_research/xagents/.github/workflows/ci.yml - 首篇提交教程示例：
/Users/dev/workspace2/agents_research/xagents/tutorials/commit/0001-bootstrap-agents-workflow.md - 参考实现：
/Users/dev/workspace2/agents_research/claude-code-best - 参考实现：
/Users/dev/workspace2/agents_research/claw-code - 主要参考实现：
/Users/dev/workspace2/agents_research/claw/openclaw
子目录约定
如果后续新增以下目录，按下面方式处理：
extracted/某子项目/: 视为候选子代码库，进入前先找本地AGENTS.mdnotes/: 研究、比对、结构分析文档tutorials/commit/: 只放每次提交对应的教程，不混放临时草稿crates/: 当前正式 Rust workspace 实现目录adapters/、skills/或类似新增目录：领域外脑、模型、工具、协议接入层
当 CI、Cargo workspace、crate 分层或教程/提交规则变化时，应同步更新本文件，避免后续 agent 按过期事实工作。