agent-claim-network AGENTS.md

AGENTS.md

本文档为 Codex 在本仓库中工作时提供指引。整体使用中文与用户交互。

项目概览

Agent Claim Network（ACN）是 Rust 实现的通用领域协作型助手，主要通过终端 TUI 与用户交互。acn 可独立运行，也可连接 Router 与 Maintainer，共享 claim、接收 policy、上报 dispute 并维护团队知识。

以当前代码与现行文档为准，不以历史设计稿或已完成 PRD 的实施清单为准。按任务查阅：

• README.md / docs/user_guide.md
• docs/architecture.md
• docs/core_behavior.md
• docs/memory_design.md
• docs/config_parameters.md
• docs/PRDs/

需求或行为有歧义时先向用户确认，不替业务方拍板。

当前架构

模块细节见 docs/architecture.md 与 src/；改动时守住所有权即可：

• Agent（src/agent/、src/session/、src/memory.rs、src/session_tui/、src/tool/）：本地 session、Memory、TUI 与工具执行；inbox 内化后才落本地变更。
• API（src/api/）：provider-neutral turn loop 与各模型 adapter。
• Router（src/router/）：可引用的 claim / dispute 检索与派生视图，不拥有 agent 私有 Memory。
• Maintainer（src/maintainer/）：policy、dispute、stale sweep、outbox；对 claim 属性的更新是建议而非强制。
• Claim DTO（src/claim/）与装配入口（src/bin/acn.rs、src/bootstrap.rs）。

默认 ACN base 目录是 ~/.acn。upstream 是 Agent 侧的运行与团队连接配置；Agent 选中后，私有运行时根目录是 <acn_home>/<upstream>/。Router 与 Maintainer 不解析或选择 Agent upstream，团队数据固定使用各自 <acn_home>/data/team/。工作区由 --cd 或启动 cwd 决定，不能与 ACN 数据目录混淆。

Rust 规范

• 异步 I/O 使用 tokio；禁止在 async 上下文直接做阻塞网络、文件、子进程或 sleep。
• async 锁优先 tokio::sync::Mutex，不要持有同步锁跨越 .await。
• 应用入口使用 anyhow::Result；模块边界优先 thiserror。
• 避免 unwrap、expect、panic!、todo!、unimplemented!。确有静态安全前提时就近写清原因。
• 降位转换使用 TryFrom / TryInto，不要直接 as。
• 路径使用 Path / PathBuf 与 join，不要拼接路径字符串。
• YAML 使用 serde-yaml-ng。持久状态写入遵循现有原子写、文件锁和恢复边界，不自行发明第二套。
• 复用现有配置结构；重要 endpoint、路径、模型和超时不在业务代码硬编码。
• 日志沿用项目现有 log/ftlog 管线，按可恢复程度选择 error、warn、info、debug、trace。
• 文件过大或职责混杂时拆到现有同级模块，避免为单文件创建无意义层级。
• 模块顶部用简短中文说明职责；注释解释约束和原因，不复述代码。

数据与安全边界

• USER.md 永不进入 claim；MEMORY.md 是 agent 私有内容，不直接上传团队服务。
• Router 只返回可引用的候选 claim 与 dispute 信息，不拥有 agent 私有 Memory。
• Maintainer 的 claim 属性更新是建议；agent 在 inbox 内化后决定本地变更。
• 单人模式不得发起团队网络请求，也不为未来补传偷偷积累团队上传队列。
• Team Auth、MCP token、LLM key 只保存环境变量名；仓库任何位置都不得出现明文密钥或其他真实 secret，包括测试、fixture、示例、文档、日志和错误信息。
• 仓库任何位置都不得出现内网域名；localhost、127.0.0.1 等明确的本机回环地址除外。测试与示例需要域名时使用标准保留域名或中性占位符。
• 路径、变量名、fixture 和示例数据不得包含可能暴露真实用户名、姓名缩写或内部账号的信息；使用 user、example、临时目录等中性名称。
• Rust、JavaScript/TypeScript、Python、Shell等代码文件中，不以 Codex/GPT/OpenAI、Claude/Claude Code/CC/Anthropic、Hermes/HA/Hermes Agent、GA/Generic Agent、非凸/非凸科技/ft.tech/non-convex/ftai 作为实现来源、兼容对象、架构标签、变量/fixture 名或注释描述。运行时真实默认值及协议、模型、API、序列化标识等兼容性所必需的名称除外，例如 gpt-5.5、openai_chat_compatible。
• Markdown 与 HTML 文档不受上一条外部主体名称限制，但仍必须遵守明文密钥、内网域名和真实用户信息的禁令。
• 修改协议 DTO 前检查持久化兼容、HTTP 客户端/服务端、prompt 与相关测试。