circle-server 第二阶段简报（修订 2）：资产先行，再到云执行

历史文档（2026-10-21 标注）：本文是已退役的任务与审批服务器第二阶段的简报，已被 Hub r4 简报取代，只作记录保留，不是现行指令。

2026-10-12。这一版取代 docs/server-s2-brief.md 里「bug 闭环」的范围和验收。方案页面是私有的 claude.ai 页面，你打不开，本文件是它的可执行摘要。分支继续用 server-s2；已提交的通用对象和关联存储（ed537f1）、核心守卫（2fcf0e3）、PLM 只读契约记录（7376cf2）继续有效。Circle 仓库由 Claude 负责，你不要改。

1. 目标

第一阶段的整体目标：把 SyntheticReference 已有的能力（产品问答、用例编译、用例评审）通过 Circle 和 circle-server 接起来，以知识库为核心。顺序如下：

  1. 先把 SyntheticReference 的对接做成 server 的资产。
  2. 再让 Circle 通过工具目录发现这些资产。
  3. 然后由 Claude 在 Circle 里用这些工具开发完整的脑图编译技能。
  4. 最后把它推到 server 上，作为技能包登记，由 server 上无界面的 Circle 执行，也就是云执行。

本简报覆盖 server 侧的第 1、2、4 步。

所有东西都按通用组件做，不写死任何产品线。FAMX 是第一个产品线包：它由配置、知识映射和技能包组成，不是核心代码。用户提出的琐碎知识，例如「禅道缺陷的 bugzillaID 能对上构建站点的修复清单」，作为带证据的声明进知识库，不做成专门功能。

2. 授权和边界

授权与上一版简报相同：

  • 本机 TypeScript 实现，依赖写精确版本。
  • 本机启动 PostgreSQL、server 和 worker。
  • 只读参考 SyntheticReference（../synthetic-reference-engine）。

工作区里的 parse5、saxes 两项依赖准备可以采用。

不允许，或仍需先问用户：

  • 运行、import 或复制 SyntheticReference 代码（ADR 0001：用 TypeScript 重写，只迁需求、行为、数据和验收样本）。
  • 连接真实系统。开发和验收一律用合成桩；真实系统的冒烟由用户或 Claude 在运行时配置后进行。
  • 调用付费模型；改动自动化环境；push、PR 和部署。

仓库是公开的：

  • 提交里不能出现内网地址、凭据、真实业务数据或本机绝对路径。
  • SyntheticReference 的知识数据和封存用例是真实数据，只能放在本机的 server 数据目录里，不进仓库。

3. 四个通用组件

3.1 资产登记

server 持有的每样东西都是资产：

  • 连接器实例
  • 凭据引用
  • 知识源和快照
  • 环境资源
  • 技能包
  • 触发器
  • bot（技能包、触发器、渠道和身份的组合）

每个资产都有：负责人、所属范围（产品线或项目）、版本、声明（读什么、写什么、用哪些凭据）、健康状态（最近检查时间和结果）、生命周期（草稿、已批准、运行中、停用）和审计记录。

提供登记、查询、状态变更、健康检查的接口，按权限过滤。

凭据：

  • 值只写不读，只在执行时注入 worker。
  • 目前允许把「某人的个人凭据」登记为某个连接器实例的凭据引用，以后再换成服务凭据。

3.2 连接器 SDK v1 和四个通用连接器包（全部只读）

连接器 要做到 SyntheticReference 参考
文档服务（WebDAV） 列目录、取文件，按 etag 或修改时间加大小做增量，原件记 SHA-256；转换作为可替换的方法挂接 main/kms/webdav_sync.py、main/famx_doc_sync.py、kms/manual_catalog_store.py
构建站点 首页 → 版本线页 → 构建（名称、构建时间、发布日期）→ 命令树 XML、修复清单；命令树解析成「构建有哪些命令和参数」 main/sync/command_tree_sync.py、scripts/maintenance/build_vendor_stdlib.py
禅道 PLM 查询 按进度记录里的只读契约 已登记
自动化环境 经跳板机只读查看：环境资源列表、拓扑、设备状态。命令白名单，不执行任何改动；自动化框架镜像只读同步 main/sync/framework_sync.py、knowledge/data/auto_env 的结构

每个连接器都要有：

  • 合成桩；
  • 失败分类：不存在、没权限、登录失效、源不通；只有确认不存在才能缓存；
  • 增量游标；
  • 原始返回的 SHA-256 留证。

构建站点的平台（虚拟化、系统或芯片变体）与版本线分别保存，平台不能当作型号。版本查询在指定版本线中筛选已正式发布且命令树中具备相应命令的构建，再结合修复清单和发布日期选最新正式构建。命令树只能证明命令/参数存在，完整功能语义还需对应产品证据；缺证据明确披露。

3.3 知识库

按 references/platform/snapshot/docs/knowledge-v1.md 的六种记录实现最小可用版本：来源修订、证据、实体、声明、评估、知识快照。在已有对象和关联存储上扩展。

  • 检索：先做精确、前缀、目录和全文（PostgreSQL 全文）。SyntheticReference 实际也没用向量检索。
  • 声明的收集接口：用户或技能提交带证据的声明，状态从候选开始；审核以后进入新快照。
  • footprint 这类模型生成的事实：只能作为候选声明导入。

知识分两类，共用六种记录，每类记录增加 knowledgeCategory 和 sourceType，并在检索结果中显示：

  • 产品知识来自连接器同步的文档、命令树、缺陷与构建记录；由程序抽取，钉住来源修订，以来源为准，权限跟随来源系统，检索优先。
  • 沉淀知识来自用户明确允许共享的 Circle 会话片段、技能/bot 运行和评审决定里的纠正与发现。定时整理技能包用脚本模型抽取事实、做法、纠正，去重并引用原始片段和工具返回；先为个人候选，经产品来源复核或人工审核后才可提升到团队知识。不覆盖产品知识，冲突单独记录并显示。

SyntheticReference 的 session-checkpoint、memory-consolidator、kb_memory_search 仅只读参考行为，不执行、不复制代码或配置，也不读取真实会话用于开发验收。

3.4 工具目录、技能包和执行引擎

工具目录

  • 给 Circle 用：返回调用者能用的工具，每个工具带名称、说明、参数 schema、读写类别和所需权限。
  • 读工具直接返回；长操作变成任务，复用第一阶段的任务和事件流。
  • 写一份客户端交接文档，Claude 据此让 Circle 登录后自动注册这些工具。

技能包格式

  • 一份清单：id、版本、负责人、用到的工具、允许的触发方式、输入输出、模型需求。
  • 加上 SKILL.md 和 TypeScript 脚本。

提交流程

  • 提交时按内容寻址，附试跑记录。
  • 机械核对：试跑里有没有用到声明之外的工具。
  • 审批沿用第一阶段的审批，批准后登记。

执行引擎

  • worker 里运行无界面的 Circle，加载技能包，调用工具目录里的工具。开发阶段只用脚本模型。
  • Circle 运行内核以精确版本的依赖引入，不改 foundation/circle 的字节。引入方式有疑问就先问。

触发方式

  • 手动、定时、事件（连接器事件）三种，跑的都是同一个技能包。
  • 每次运行是一条任务；同一事件只跑一次，重启后不丢不重。
  • 输出渠道第一版只用 Circle 事件流，渠道接口可扩展；企业微信及其桩延后，不在本阶段必做。
  • 定时触发验收用上述整理技能包（脚本模型），只处理用户授予共享许可的合成片段，并保留个人候选/团队提升和去重边界。

第一阶段的脑图编译

  • 从核心移出，改为 FAMX 产品线包里的方法或技能包。
  • lbx-healthcheck 撤下。它验证的机制改用中性的合成设备操作继续测。

4. 验收

每一幕是 tests/acceptance 里的一组自动测试：

幕 必须证明
1 资产 登记连接器实例和个人凭据引用；凭据值不出现在任何返回、日志和审计里；健康检查；生命周期；越权不可见
2 连接器 四个连接器对合成桩：读取、增量、失败分类、留证；自动化环境的白名单之外的命令被拒绝
3 知识 产品知识钉住桩来源修订并按源权限过滤；两类记录与检索标明类别，产品优先；声明带证据、审核后进快照；沉淀候选不进正式快照、个人范围对他人不可见、冲突被标出，沉淀不覆盖产品知识
4 目录 目录只列调用者能用的工具；读工具同步返回；长操作变任务，能补读事件
5 技能包 提交附试跑记录；用了未声明工具的被拒；审批后登记；server 上无界面 Circle 用脚本模型跑完，产出进知识库，事件送达
6 触发和 bot 定时运行整理技能包（脚本模型），只整理获准共享的片段，去重后产出个人候选并保留原片段/工具返回；事件触发不重复；输出仅 Circle 事件流；重启后不丢不重，渠道保持可扩展
7 通用 第二个虚构产品线包用同一套核心跑通；核心里搜不到具体系统、产品和能力名（核心守卫通过）；第一阶段的测试继续通过

5. 顺序

  1. 第一笔提交：登记本简报，更新 AGENTS.md 范围。
  2. 资产登记和凭据引用（第 1 幕）。
  3. 连接器 SDK v1 和四个连接器桩（第 2 幕）。
  4. 知识库最小版本和入库（第 3 幕）。
  5. 工具目录和客户端交接文档（第 4 幕）。交接文档写完就告诉用户，Claude 要开始 Circle 侧。
  6. 技能包和执行引擎（第 5 幕），触发和 bot（第 6 幕）。
  7. 第二产品线包、核心守卫全绿、第一阶段测试回归（第 7 幕）。

6. 工作方式

与上一版相同：

  • 每幕先写验收测试并确认失败，再实现。
  • 显式写出要提交的路径，提交信息是一句首字母大写的英文祈使句。
  • 记下实际跑过的命令和结果，每步更新 docs/server-s2-progress.md。
  • 遇到需要用户决定的事就停下来问。

把本文件（主工作树里未跟踪的 docs/server-s2-brief-r2.md）提交进 server-s2，然后删掉主工作树里的副本。