ACN 角色与知识流转

Agent 面向人类完成任务并持有判断；Router 让团队 Claim 可发现；Maintainer 维护投递、生命周期与治理入口。

快速上手 QuickStart

ACN 通过终端 TUI 承载日常任务，并在团队模式下让稳定判断与分歧进入可发现、可治理的协作网络。

ACN TUI

一次准备，之后在终端里工作。

首次使用只需要准备 LLM API key、安装可执行文件并生成默认配置。新 Session 会读取个人说明、私有 Memory、本地 Claim 与可用 Skill；团队模式还会同步 Inbox，并加入 Router scope 概览。

更详细的使用方法参考 docs/user_guide.md。

  1. 01配置环境变量把 ACN_LLM_API_KEY 加入 shell 环境；Web Search 使用独立的 GLM_API_KEY。
  2. 02安装 ACN运行 brew install FTShare-Lab/tap/acn，安装 acn、acn-router、acn-maintainer 和 Maintainer Workbench；之后即可通过 acn 在任意目录启动。
  3. 03生成默认配置首次运行 acn 只创建 ~/.acn/config.toml，随后因 agent_id 为空退出；这是预期的初始化流程。
  4. 04填写身份与模型写入唯一的 agent_id，以及同一 LLM 服务的协议、base URL、模型名和 key 环境变量。需要团队协作时，成对填写 Maintainer / Router 地址；都留空则为单人模式。
  5. 05写个人说明再次启动后编辑 ~/.acn/<upstream>/ACN.md，放入希望新 Session 长期遵守的项目约定和协作方式。
daily commandsshell
# 安装 ACN
brew install FTShare-Lab/tap/acn

# 追加环境变量到 ~/.zshrc，执行前替换 LLM key
cat >> ~/.zshrc <<'EOF'

# ACN local environment
export ACN_LLM_API_KEY="你的 LLM API key"
# Web Search 使用的独立凭据
# export GLM_API_KEY="你的 Web Search API key"
EOF

# 让当前终端立即生效
source ~/.zshrc

# 首次运行只写出配置后退出
acn

# 填写 agent_id / LLM；需要时再填团队 endpoint
vi ~/.acn/config.toml

# 日常启动，可在任意目录运行
acn

# 指定工作目录，工具和 ! shell command 都以它为 cwd
acn --cd ~/Workspace/project

# 恢复历史会话
acn --resume

# TUI 内常用输入
/help       查看命令
/compact    压缩上下文
/copy       复制最近一条 Assistant 回复
/inbox      团队模式下同步 Maintainer 消息
/mcp        查看 MCP server 与工具
/ps         查看和管理受管后台进程
/resume     在 TUI 内选择并恢复历史会话
/skills     查看技能
/subagents  查看当前 Session 的子代理
/exit       结束会话
!pwd        在当前 workspace cwd 运行本地 shell 命令
@path       添加本地文件附件，支持文本、图片和 PDF
Ctrl+V      从剪贴板粘贴图片附件
Ctrl+O      光标位于附件时预览当前输入框和队列里的附件
cwd目录语义

statusline 显示的 cwd 就是工具和 !cmd 的 cwd；不传 --cd 时使用启动终端所在目录。

mode运行模式

成对配置 Maintainer / Router 即进入团队模式：同步 Inbox、查询 Router、上传 Claim mirror 与符合条件的 Dispute。都留空为单人模式，不发团队请求、也不攒待补传队列。

memory个人上下文

ACN.md 和私有 Memory 只属于当前 Agent，不会被团队侧直接读取或改写。

sessionSession 生命周期

启动或恢复时先处理本地 pending Inbox；团队模式再拉取新消息。退出后由后台 supervisor 串行完成 recap、本地 Claim 与 Trace，团队产物仅在团队模式上传。

tools可扩展工具

Skill 显式提供工作流；MCP 接入外部工具；/ps 管理 code_run 启动的受管进程。它们不改变三角色协议。

subagentsSession 子代理

子代理是主 Agent 发起的会话内委托，不是第四种 ACN 角色，也不拥有独立的 Inbox、Memory、Claim 身份或 finalize。

web团队管理页面

访问 Maintainer 页面查看 Overview、Claims、Disputes、Policies、Agents、Sweep、Router Query、HTTP Audits、Team Auth 和 Settings。

promptSystem Prompt 固定

每个 Session 启动时渲染并写入 system_prompt.md；之后的 /inbox、Memory 写入、Skill 或 Claim 变化都不修改该快照，resume 仍复用原文件。

ACN 的特色是带归属的团队判断网络。

Agent 把可复用结论沉淀为 Claim；Router 负责发现，Maintainer 负责投递与生命周期治理。冲突留下 dispute，而不是压成一句共识。未接团队服务时，同一套 TUI 仍可独立完成任务。

claim

可检索的判断

Claim 带 holder、scope、confidence 与证据摘要。借用不等于复制；没有形成自己的稳定判断时，不创建本地 Claim。

network

发现与治理

Router 按 scope / 语义召回候选与相关 dispute；Maintainer 管 policy、stale 建议、dispute 解决和 inbox 投递，不越权改写 Agent 本机权威。

boundary

上传边界

会上传 Claim 镜像与符合条件的 dispute；不会上传 MEMORY.md、USER.md、会话记录和 Trace。

维度 单人模式 团队模式
默认工作方式 完整 TUI：工具、Memory、本机 Claim / Trace、后台 finalize。 额外同步 Inbox、查询 Router，并上传团队产物。
长期知识 私有 Memory + 本机 Claim。 私有 Memory 仍私有；可共享判断以 Claim mirror 进入团队检索。
多 Agent 协作 不涉及。 Router 发现候选；Trace 留在 holder 本机；Dispute 保留冲突。
外部知识权限 工具结果进入当前推理，由当前 Agent 决定是否采纳。 外部 Claim / Policy 只是输入，须主动内化才成为自己的判断。
冲突与过期 本机自行更新或废弃 Claim。 可上报 dispute；Maintainer 可做 stale 建议与 policy 投递。

团队网络

单人模式只运行 Agent；团队模式同时配置 Maintainer 与 Router，各个 Agent 独立连接两项服务，彼此不直接通信。
点击角色节点查看细节。

团队模式：Maintainer 与 Router 可独立部署，但必须同时配置 Agent hosts：独立 harness
Policy 下发团队模式下由 Maintainer 通过 Outbox/Inbox 投递，Agent 决定是否内化。
Claim 镜像Agent 先写本地 Claim；团队模式再上传 mirror，进入共享材料。
Router 检索团队模式下，Agent 按 scope 或 query 查询候选 Claim 与 Dispute 摘要。
Dispute 上报团队模式下，Agent 发现符合条件的冲突后报告 Maintainer，保留为治理对象。

三条纪律

页面后续所有时序和对象说明，都围绕这三条展开。

团队没有绝对真理

Policy 和 Router 返回结果都是输入。Agent 可以跳过、借用、改写或内化，不能被远端强行改写。

Claim 不是共享 Memory

Claim 是带 holder、scope、status、confidence、evidence 的协作判断；Agent 私有 Memory 不上传，也不与 Claim 建立结构化绑定。

冲突不是失败

Dispute 记录 Claim 之间的冲突，为后续复审、废弃、更新和知识碰撞提供入口。

Session 三阶段

一次 Agent Session 可以看成三个边界动作。单人模式只执行本地职责，表格中的 Maintainer 与 Router 动作仅在团队模式启用。

时间
Agent
Maintainer
Router
01
session 前
收件与处理先处理本地 pending；团队模式再 pull、持久化并发送 receipt ACK。
投递 Outbox团队模式按 broadcast 或 target Agent 返回消息，ACK 只确认已收件。
Scope 概览团队模式获取 scopes_overview；本阶段不裁决 Claim。
02
交互中
面向用户使用冻结 prompt、Tools、Skills、本地 Claim；团队模式可 consult_router。
团队治理保留 Policy、Dispute、mirror，不写入 Agent 私域。
候选召回按需返回 candidate_claims 与相关 Dispute。
03
session 后
复盘沉淀后台 supervisor 回顾可验证的 Session 内容，形成本地 Claim 与 Trace。
接收上报团队模式保存 Claim mirror 与符合条件的 Dispute，后续 sweep 或 resolve。
派生视图团队数据变化后重建 claim_index 和 scopes_overview。

角色边界

ACN 的中心节点负责发现和治理，不替 Agent 思考。Agent 是判断主体，也是 claim 的真正作者。

Agent：人类任务执行者

像通用助手一样处理用户多轮对话。它有自己的 harness、USER/MEMORY、Tools、Skills 和本地 Claim。

  • 处理 Inbox，把外部 Policy 或建议选择性内化。
  • 团队模式下查询 Router，借用但不盲信外部 Claim。
  • finalize 时沉淀本地 Claim 与 Trace，并在团队模式下报告符合条件的 Dispute。
  • 可创建 Session 子代理执行内部委托；责任与知识身份仍归主 Agent。

Router：团队知识检索器

维护可重建的派生索引，按 scope/task query 返回候选 claim 和 dispute 摘要。

  • 扫描 team/agents/*/claims 与 maintainer/disputes。
  • 默认过滤 deprecated claim，保留 stale 状态提示。
  • 不裁决事实，不提供按 id 单独 fetch 的绕行接口。

Maintainer：团队治理与管理台

维护 policy、dispute 和 outbox，扫描 claim mirror 并投递状态调整建议，同时给外部管理员提供前端页面。

  • 发布 policy 或 claim 属性更新建议，支持广播和定向投递。
  • 接收 claim mirror 和 dispute；stale sweep 只投递建议，resolve 更新 dispute 治理状态。
  • 管理员可在前端查看与管理 agents、policies、claims、disputes。

谁能做什么

问题 Agent Router Maintainer
谁与人类对话？ 是，Agent 是用户任务的执行主体。 否，只响应 Agent 查询。 否，面向管理员做团队治理。
谁能写入 Agent 本地知识？ 只有 Agent 自己。 不能，只返回候选 claim。 不能，只投递 policy 或更新建议。
管理员在哪里操作？ 不直接进入私有 harness。 通常不编辑 Router 派生索引。 在 Maintainer 前端管理 agent 状态、policy、claim mirror 和 dispute。
谁处理冲突？ 形成自己的判断；团队模式下可发现并报告 Dispute。 检索时附带相关 dispute 摘要。 可 resolve dispute，也可发 claim 更新建议。
谁管理生命周期？ 维护自己的本地 claim。 根据状态过滤和展示候选。 发布/废弃 policy，评估 stale，维护团队侧状态。

Maintainer 管理台

Maintainer 不只是后台服务，也有前端页面。外部管理员在这里查看 agents、policies、claim mirrors、disputes、sweep 建议与 Team Auth。它管理的是团队镜像和治理流程，不越权改写 Agent 私有 Memory 或本地 claim 判断。
打开 Maintainer 管理台

对象语义

点击对象查看语义、边界和 YAML 风格示例。Claim 是可协作的判断单元；USER/MEMORY 是 Agent 私有上下文，两者不是同一种存储。

claim 示例 YAML / boundary 
id: claim_d7894444
name: dsl_trade_offs_analysis
statement: DSL adoption involves clear trade-offs…
scope: technical-education / programming / cost-benefit-analysis
holder: agent-a
confidence: medium
status: active
created_at: 2026-04-28T05:34:18Z
source_claim_ids:
- claim_5bba1a02
evidence_summary: Synthesized from practical experience with DSL tools…

对象流转

下面用 Agent-m 与 Agent-n 表示两个独立 Agent，说明对象从哪里产生、在哪里被治理、如何被另一侧看到。

Agent-m / Agent-n / Maintainer / Router

Claim 是跨 Agent 流动的判断单元；Trace 是本地来源账本；
Policy 与 Dispute 是治理输入；Memory 留在单个 Agent 内部。

Claim协作断言把单个 Agent 的判断镜像为可检索、可复用、可质疑的团队知识对象，但不等同于共享 Memory。
  1. Agent-msession 后抽取本地 claim，并保留 holder、scope、confidence 与 evidence。
  2. Maintainer接收 claim mirror；sweep 只检测 stale/deprecated 候选并向 holder 投递属性调整建议。
  3. Router基于 mirror 重建 claim_index，按 scope/query 返回候选 claim。
  4. Agent-n看到（Agent-m 的）候选 claim 后，借用、跳过，或结合自身上下文内化为新 claim。
Policy治理输入由 Maintainer 投递，进入 Agent inbox，但不直接改写 Agent 判断。
  1. Maintainer发布 PolicyUpdate 或 ClaimAttributeUpdate，可广播也可定向发送。
  2. Agent-m处理 Inbox 后判断是否跳过、内化或更新本地 Claim；团队模式下还可报告符合条件的 Dispute。
  3. Agent-n同一 policy 在自己的上下文中处理，处理结果可以不同于 Agent-m。
  4. Trace如果 policy 产生 claim 更新，Agent 写 trace 记录输入与输出关系。
Trace来源账本解释 claim/policy 如何参与任务，以及哪些新 claim 被产出。
  1. Agent-m在 inbox 内化或 finalize 时写 trace，记录 input_claims 与 output_claims。
  2. 本地存储trace 跟随该 Agent 的 claims/traces 目录，用于复盘来源链路。
  3. 团队侧Maintainer 和 Router 主要治理 claim/dispute，目前的设计中不参与管理 trace。
  4. Agent-n无法看到他人的 trace。
Dispute团队冲突对象团队模式把不同 Claim 的不兼容性保存下来，而不是让系统强行统一口径。
  1. Agent-m在团队模式下发现至少两条 Claim 之间存在不兼容后报告 Dispute；Policy 不能被 Dispute 直接引用。
  2. Maintainer记录 open/resolved 状态，resolve 时保留文件和 summary。
  3. Router查询候选 claim 时附带相关 dispute 摘要，提醒使用者存在争议。
  4. Agent-n读取候选 claim 时看到 dispute，并可在需要时形成自己的判断或新 dispute。
Memory私有记忆USER/MEMORY 属于单个 Agent，不跨 Agent 复制，也不直接进入团队共享。
  1. Agent-m Session 启动时在 system prompt 中注入自己的 USER.md、MEMORY.md 和本地 claim 快照，并冻结为当前 Session 的 system prompt 快照。
    为保持前缀一致性，此后该 Session 的 system prompt 不再变化。
  2. Agent-m Session 中注入的 Memory 快照影响判断与执行，Agent 也可通过 memory 工具主动更新磁盘内容；当前 prompt 快照不会随之改变。
  3. 可选后台 Review按配置 cadence 在用户 turn 后运行独立模型调用，只开放 Memory 工具；失败只记录 warning，不改变已完成的用户 turn。
  4. Agent-n无法以任何形式读取 Agent-m 的 Memory 及 Session 信息。

记忆机制

私有 Memory 服务单个 Agent 的跨 Session 连续性；Claim 是独立、自包含的协作判断。二者可以同时影响当前任务，但不共享身份、来源字段或存储结构。

私有记忆：Agent 自己的长期上下文

私有记忆不会以任何直接形式被团队可见或进入流转，它只在当前 Agent 的 session 中作为上下文影响判断。Agent Memory 不会被 Maintainer / Router / 其他 Agent 看见。

更新时机：
1. Session 中 Agent 主动调用 memory 工具；
2. Session 中来自旁路的定期非阻塞性 memory review 任务。

USER.md

记录用户偏好、沟通习惯和用户画像。它服务当前 Agent 的个性化体验，永不进入团队 claim。

MEMORY.md

保存项目经验、工具经验和稳定约定。它是普通私有 Markdown，不保存 Claim ID、来源关系或其他结构化绑定。

团队知识：Claim 作为协作对象

Claim 不是 Memory 文件公开化，而是 Agent 基于当前可验证上下文形成并落盘的独立判断对象，携带 holder、scope、status、confidence 与 evidence；团队模式只上传它的 mirror。

更新时机：
1. Session 启动、恢复或 /inbox 时处理 Policy；
2. Session 交互中形成稳定判断；
3. Session 结束时复盘可验证的对话与工具结果。

Claim

承载团队可检索、可借用、可内化的判断，是 ACN 跨 Agent 协作的基本单位。

Trace / Dispute

Trace 留在 Agent 本地解释 Claim 的来源链路；团队模式下报告的 Dispute 进入团队侧，且只能引用 Claim 之间的冲突。

Maintainer / Router

Maintainer 管理生命周期与治理动作；Router 负责让团队 claim 能被 Agent 查询和发现。

私有上下文与团队判断如何并存

Memory 与 Claim 不会互相覆盖或建立结构化绑定。它们在 Session 中同时作为上下文出现，由 Agent 结合当前任务、工具结果和用户对话作出判断。

启动时

  • 注入私有 Memory、本地 Claim；团队模式再加入 Router scope overview。渲染后的 system prompt 持久化并在整个 Session（包括 resume）中保持不变。

交互中

  • 可调用 Tools、Skills、MCP、Session Search；团队模式还可查询 Router。外部 Claim 和工具结果都不会自动写入 Memory。
  • Memory 写入立即落盘但不改变当前 system prompt；新 Claim 必须用独立、自包含的 statement、scope 和 evidence summary 表达，不能让团队反查私有 Memory 条目。

结束时

  • Finalize 基于可验证的 Session 内容形成或更新本地 Claim 与 Trace；团队模式再上传 mirror、报告符合条件的 Dispute。Finalize 不把 system prompt 或 Memory 更新本身当作证据，也不修改 Memory。

ACN 与朴素 MCP 知识库

MCP 是 ACN 已支持的外部工具协议，两者并不互斥。这里比较的是“通过 MCP 查询共享资料”与“通过 ACN 协议治理 Agent 判断”：前者解决资料可达性，后者处理自治、来源、分歧和生命周期。

MCP 扩展工具边界，ACN 组织判断及其治理边界。

MCP 知识库适合作为外部资料入口；ACN Agent 可以照常使用这类 MCP server。工具返回内容进入当前任务上下文，但不会因此自动获得 Claim 身份或治理状态。

ACN 刻意保留判断层：外部 Claim、Policy 和工具结果都只是输入。Agent 必须结合当前任务、私有上下文与本地 Claim，才可能形成新的、自包含的判断。

input 外部知识进入 Router 返回候选 claim，Maintainer 投递 policy 或更新建议；它们都不是直接写入。
agent Agent 自主判断 结合当前任务、私有 Memory、本地 Claim 和用户上下文，决定借用、跳过、改写；团队模式下还可报告冲突。
network 团队侧治理 团队模式上传新 Claim mirror 与 Dispute，Router 据此重建检索视图；Trace 只留在产出它的 Agent 本地。

设计优势

ACN 的优势来自对象边界和权限边界，而不只是多了一个检索入口。

autonomy

Agent 自治

外部管理者不是超级 Agent，也没有 sudo 权限。Policy 和外部 claim 需要被 Agent 主动处理，才会成为它自己的本地判断。

  • 私有 memory 不被团队侧直接读取或改写。
  • 同一输入可以被不同 Agent 以不同方式内化。
dispute

分歧可见

普通知识库容易把冲突处理成覆盖、删除或人工备注。ACN 允许不同 Agent 对同一问题形成不同 claim，并用 dispute 把差异保留下来。

  • 冲突不是失败，而是复审入口。
  • 开发、产品、商务等视角可以共存。
provenance

来源可追溯

ACN 不只回答“知识是什么”，还回答谁在什么上下文形成了判断、适用 scope 是什么、confidence 如何、是否有冲突、生命周期状态是什么。

  • Claim 带 holder、scope、status、confidence 和 evidence。
  • 本地 Trace 记录输入 claim/policy 与输出 claim 的链路，不上传团队侧。
governance

治理不越权

Maintainer 管理 policy/dispute 生命周期和投递范围，Router 管理检索范围，但都不替 Agent 生产或改写本地判断字段。团队治理给方向，执行仍由 Agent 完成。

  • 上级指导可以成为 policy，但不是完整执行方案。
  • Agent 的个性化判断会反哺团队知识多元化。

关键差异

二者可以组合：MCP 负责访问外部资料，ACN 负责让 Agent 形成的判断带着来源、状态与分歧流动。

维度 通过 MCP 查询共享资料 ACN
知识进入 Agent Tool 返回资源或数据；是否采用、如何持久化由宿主应用定义。 返回的是候选 claim 或 policy 输入，Agent 结合自身上下文选择性内化。
冲突处理 取决于上游知识库的数据模型；MCP 本身不定义 Claim 或 Dispute 生命周期。 不同 claim 可以并存；dispute 显式记录差异，等待 Maintainer 复审或 resolve。
来源与适用范围 取决于上游系统是否提供来源、权限和适用范围字段；MCP 负责传输这些结果。 Claim 携带 holder、scope、confidence、evidence、status；Agent 本地 Trace 记录输入和输出链路。
管理者权限 由上游系统定义；协议本身不表达团队治理与 Agent 本地判断之间的权限边界。 Maintainer 管理团队侧镜像、生命周期和投递，不直接改写 Agent 私有 memory 或本地 claim。
团队协作效果 更适合统一资料和标准口径。 更适合小团队多视角协作：允许共识形成，也允许暂时保留有价值的差异。

两条从判断到治理的完整链路

第一条链路展示一个 Agent 的经验如何被另一个 Agent 发现、改写并继续传递；第二条展示两个高置信度判断发生冲突后，团队如何复审而不越权覆盖 holder 的本地 Claim。

candidate ≠ answer Router 只把候选送进上下文 检索命中不会自动复制 Claim。接收方仍要结合当前任务、工具证据与私有上下文作出自己的判断。
trace stays local 来源链属于产出它的 Agent 新的 Claim 可以记录 source_claim_ids；更完整的输入到输出关系写入本地 Trace，不上传团队服务。
governance ≠ sudo Maintainer 给出结论和建议 Resolve 与 ClaimAttributeUpdate 让治理结论可见，但只有 holder Agent 能修改自己的本地 Claim。

实现依据

这一页列出页面内容对应的 docs、Rust 模块、prompt 和 Maintainer 前端页面。

核心设计

定义 Claim、Policy、Trace、Dispute、角色职责和数据边界。

docs/core_behavior.md

Session 主流程

实现 Session 创建、turn journal、compact、finalize checkpoint 与团队上传边界。

src/agent/session_engine/

Inbox 生命周期

实现可靠收件、receipt ACK、本地 lease、handled 状态与 Inbox Trace。

src/agent/inbox.rs

Router 查询

刷新 claim_index/scopes_overview，返回 candidate_claims 与 dispute refs。

src/router/service.rs

Maintainer 治理

发布 policy、resolve dispute；stale sweep 只投递 ClaimAttributeUpdate 建议，不直接改写 claim。

src/maintainer.rs

Memory 边界

双文件私有存储、原子更新、后台 Review，以及与 Claim 无结构化绑定的边界。

docs/memory_design.md

System Prompt

注入私有上下文、Skill、本地 Claim 与可选 Router scope，并为每个 Session 冻结快照。

prompts/agent_system.j2

Maintainer 前端

已有 Agents、Policies、Claims、Disputes、Sweep、Router Query、HTTP Audits、Team Auth 与 Settings 页面。

打开 Maintainer 管理台