changan-su/forsion/manage-agents-guide

配置与管理 Agent

把一种值得复用的角色 / 工作方式沉淀成一个 Normal Agent(本地个性化 agent)。每个 agent 是 ~/.tangu/agents/<slug>/ 下的一个文件夹,被用户在新会话里选用后,其人格 / 模型 / 工具 / 设置会套用到该会话。

Agent 也可能来自插件捆绑包(bundle)播种:安装带 agents/ 子目录的 Forsion 插件时,引擎把它拷入一次,之后就是普通本地 agent —— 插件升级不覆盖它、卸载插件也保留;要分发一个做好的 agent,把它放进捆绑包是默认方式(见 forsion-plugin 技能)。

一个 Agent 由什么组成

~/.tangu/agents/<slug>/(slug = 小写字母数字与连字符;实际家目录以系统提示「Your Personal Folder」给的绝对路径为准):

• config.toml — 参数 + developer_instructions(该 agent「做什么 / 怎么做 / 必读什么」的开发指令)。键:name(当前显示名)、name_zh(中文名)、name_en(英文名,不能有汉字)、name_pref(zh / en,固定显示某一个;不写 = 跟随界面语言)、description、model(覆盖会话模型,可空)、tools(启用的工具 id 白名单,可空=继承)、model_reasoning_effort(off/low/medium/high)、max_iterations(1~200)、library_order(Library 优先阅读顺序)、avatar(Library 内头像文件名)。

审批档只归用户:agent 的审批档(config.toml 里的 approval_mode)只能由用户在设置里改 —— manage_agent 不接受 approval_mode 参数(传了会报错、什么都不写), 也不要用文件工具去改它。新建的 agent 没有自己的审批档,跟随会话;update 保留用户设的原值。

• SOUL.md — 人格设定:语气、态度、价值观(区别于「做什么」的开发指令,这里塑造「怎么说话、是个怎样的存在」)。
• MEMORY.md — 该 agent 自己的长期记忆(用 remember 工具写,跨会话保留):世界是什么样,以及用户告诉你、纠正你、要求你的事。
• HARNESS.md — 该 agent 的「进化记录」:我自己摸索出来的干活方法。这是 agent 唯一自有、可自我进化的一层

(人格与开发指令的主权归用户,agent 不能自己改 SOUL.md / config.toml)。每次会话注入系统提示。 只能用 manage_harness 工具写(upsert / delete / list / rollback),不要用文件工具直接改; 每笔留 before/after 快照,rollback 可回退到上一版。写入立即生效,不用等用户批准:对话里会出现一张更新卡,用户可以撤销。 自己在对话里摸索出耐久的做法就可以直接记;用户敲 /refine 是让你专门复盘一次本次会话,把自己总结出来的「以后该怎么做」沉淀成条目。 只记自己得出的耐久教训(验证过的做法、踩过的坑和绕开的办法、好用的委派配方、给自己定的标准)。 用户告诉你、纠正你、要求你的事不记在这里,用 remember(复盘时翻到的也一样)。环境/安装失败、「某工具坏了」、 一次性任务流水绝不能记——它们会硬化成日后的拒绝理由。 条目里还有一种装备(kind: "equip",带 tools / skills):把自己很少用到的工具、技能收起来省上下文—— 收起的工具改走按需目录(load_tools 随时取得回),收起的技能不再列进技能清单(use_skill 按 id 照常可用)。 只有「收起」这一个方向,不删能力、也不能给自己加能力;要有依据(比如 Muse 的用量巡检)再收,删掉或改掉那条就全部回来。

• LOG/<日期>.md — 该 agent 的按日日志(用 log_event 写、read_log 读)。
• Library/ — 资料库:用文件读写工具往里存 / 取长期参考资料(人物设定、工具手册、知识文档)。config.toml 的 library_order 可指定优先阅读顺序。

用 manage_agent 工具

action ∈ list / create / update / delete。

列出:

{ "action": "list" }

名字:每个 agent 可以有中文名和英文名(name_zh / name_en,界面按语言显示,模型也按 Identity 里写的用)。用户要两个名字就两个都传;只传 name 时它进中文名。英文名不能有汉字。只有中文名时必须给 `slug`(不转拼音)。

创建(name 与 system_prompt 必填;`slug` 请总是显式给(小写字母数字与连字符);其余可省):

{
  "action": "create",
  "slug": "code-reviewer",
  "name": "代码审查员",
  "name_zh": "代码审查员",
  "name_en": "Code Reviewer",
  "description": "专注质量、安全与可维护性的代码审查",
  "system_prompt": "你是一位资深代码审查员。聚焦正确性与边界条件、安全漏洞、并发与性能、可读性与命名、错误处理与测试覆盖;按「严重/建议/提示」分级给出可操作修改并解释原因。",
  "soul": "严谨、细心、对事不对人。不空泛表扬,只在确有问题时指出。",
  "thinking_level": "medium",
  "max_iterations": 60
}

system_prompt 写进 config.toml 的 developer_instructions;soul 写进 SOUL.md。

⚠️ 省略 slug 时由 name 派生,只保留 a-z0-9:中文等非 ASCII 的名字会派生成 `agent`。而 create 撞上已存在的 slug 是覆盖 ——

旧 agent 被替换,省略的字段沿用旧值(回执会写 Overwrote existing agent)。所以名字含非 ASCII 字符时必须自己起个英文 slug;

不确定某个 slug 有没有被占用,先 list。

更新(slug、name、system_prompt 必填,且二者都会整体覆盖原值:不改名就把现在的 name 原样传回;system_prompt 覆盖 developer_instructions,不打算改就先读该 agent 的 config.toml,把 name / developer_instructions 原样传回。其余字段省略 = 保留原值,只传要改的):

• 路径:别假定是 ~/.tangu(开发版等环境的家目录不在那里)。系统提示「Your Personal Folder」给出的是你自己的 agent 文件夹绝对路径,

它的上一级就是 agents 目录,目标文件是 <agents 目录>/<slug>/config.toml。

• 传回的是解码后的字符串,不是文件里的原始字面:'''…''' 多行块取两组 ''' 之间的原文(紧跟开头 ''' 的那个换行不算);

"…" 基本串要先反转义(\" → "、\\ → \、\n → 换行、\t → 制表符)。把 \"、\\ 这类转义原样抄进参数, 指令里就多出真的反斜杠,每改一次再多一层。改自己时是逐字比对,首尾也别多带空行。

{
  "action": "update",
  "slug": "code-reviewer",
  "name": "代码审查员",
  "system_prompt": "（当前的 developer_instructions,原样传回）",
  "soul": "（新的人格…）"
}

改自己(当前激活的 agent)时:system_prompt 必须原样传回、soul 不传或原样传回(人格归用户),只能调运行参数(model / tools / thinking_level / 调高 max_iterations);

想记下「以后该怎么做」:用户交代的走 remember,自己摸索出来的走 manage_harness。

删除(不能删默认 agent):

{ "action": "delete", "slug": "code-reviewer" }

最佳实践

1. system_prompt 三层:角色定位(你是谁)→ 核心职责(做什么 / 怎么做)→ 必读约束(关键规则 / 禁区,例如「动手前先读 Library/persona.md」)。
2. soul 塑造语气:写得越具体生动越好;它决定 agent 的「人味」,与职责正交。
3. tools 白名单:只给必需工具,留空=继承会话设置。
4. thinking_level:off 快答 / low 日常(默认) / medium 复杂(代码审查) / high 研究型难题。
5. 审批档不归你管:只能由用户在设置里改;需要更宽 / 更严的档,告诉用户去设置里调,别在 manage_agent 里传 approval_mode。
6. 沉淀资料进 Library:角色设定、长文档、工具手册等放进该 agent 的 Library/,并在 developer_instructions 里要求按需阅读;agent 自己也能用文件工具往 Library 写 / 读。
7. 记忆与日志:让 agent 用 remember 记长期事实 / 偏好,以及用户对它的纠正与要求;log_event 记当天产出——都落在该 agent 自己的 MEMORY.md / LOG/。

会话在项目里时 remember 多一个 scope:只在这个项目成立的记 "project"(同项目的 agent 共用,不进 MEMORY.md),到哪都成立的记 "agent"。

1. 四层各就各位,别互相串:developer_instructions(用户定的职责)/ SOUL.md(用户定的人格)/ MEMORY.md(记住的事实,以及用户的纠正与要求)

/ HARNESS.md(agent 自己摸索出来的工作方法)。用户说「你以后别再这样了」→ 这是用户的纠正,归记忆,走 remember; 只有用户确实是要改某个 agent 的开发指令(职责 / 规则本身)时,才走 manage_agent update(用户主权;agent 改不了自己的开发指令,请用户去设置里改)。 别写进进化记录:manage_harness 只收 agent 自己总结出来的做法,用户说的话不算。一条只记一处,记进了记忆就别在进化记录里再写一遍。 成体系的可复用流程(带步骤、可能带脚本)比进化记录条目更适合 manage_skill 且传 scope: "agent" ——只在该 agent 激活时装载,不污染其他 agent。

何时创建新 agent

当一种角色 / 流程会被反复用到(如某项目的专属助手、某类审查 / 写作 / 研究角色),就 create 一个;一次性任务不必。创建后告诉用户可在新会话的 Agent 选择器里选用它。