决策记录

本页记录关键架构判断。每条决策都应该包含背景、选择、理由和后续影响。

ADR-001：项目定位为 Agent Harness，而不是 Skills 集合

日期：2026-06-10

背景

我们希望基于 Claude Code、Codex、OpenAI Agents SDK 等成熟智能体框架，为公司 HR、行政、研发服务、财务、后勤等部门开发智能体工程。

决策

项目定位为企业级 Agent Harness / Agent Operating Platform，而不是一组 prompts、skills 或简单 hooks。

理由

• 企业能力需要工具、权限、审批、审计、评测共同保证。
• Skills 适合辅助说明，不适合承载核心业务流程。
• Hooks 适合治理和拦截，不适合承载复杂流程。
• Harness 可以让底层 runtime 随技术演进替换。

影响

后续优先建设：

• Runtime Adapter。
• Tool Plane。
• Workflow Plane。
• Policy Plane。
• Eval Plane。

ADR-002：不依赖泄露源码

日期：2026-06-10

背景

一种设想是基于 Claude Code、Codex 等的 SDK，或使用泄露源码等方式进行二次开发。

决策

不把技术方案建立在泄露源码上。

理由

• 法律和合规风险高。
• 客户公司难以接受。
• 难以稳定跟随官方升级。
• 供应链安全风险不可控。

影响

后续只使用官方 SDK、CLI、API、MCP、hooks、plugins 等可接受扩展边界。

ADR-003：企业协同入口优先支持企业微信

日期：2026-06-10

背景

目标企业主要使用企业微信作为组织通讯、通知、审批和内部应用入口，而不是飞书。

决策

后续入口设计、通知能力、身份同步、审批联动和工具接入优先围绕企业微信展开。

理由

• 贴合目标企业现有工作流。
• 减少用户切换成本。
• 企业微信通讯录、群聊、应用消息和审批能力可作为 agent 触达用户与请求确认的关键通道。

影响

后续需要补充：

• 企业微信应用接入方案。
• 通讯录和组织架构同步方案。
• 群聊上下文获取边界。
• 审批和人工确认消息设计。
• 企业微信回调事件与 harness workflow 的映射。

ADR-004：产品叙事从工具提效升级为组织变革

日期：2026-06-10

背景

随着大模型和底层 agent harness 能力增强，组织使用 AI 的方式会从个人工具试用转向组织级生产系统重构。尤其是几百人以下的小组织，更容易通过 agent harness 改造组织结构和运转方式。

决策

产品底层叙事升级为：通过企业 Agent Harness 实现 AI 平权、组织结构重构和生产力再配置，并将内部成功经验沉淀为可对外输出的智能体解决方案。

理由

• 单点提效工具壁垒较低，容易被底层模型和通用 agent 框架吞噬。
• 组织级 harness 能沉淀流程、权限、工具、审计和评测，形成长期资产。
• AI 平权可以充分动员一线员工，释放真实业务问题和改造机会。
• 释放出来的人力、资金和知识可以被重新配置到培训、交付和外部方案业务。

表达边界

内部可以使用“广泛动员 + 强组织执行”作为战略类比。对外客户沟通中，应转译为商业和组织设计语言，避免政治化表达影响销售、合规和品牌接受度。

影响

后续产品设计需要同时覆盖：

• 员工入口。
• 组织运行看板。
• workflow 和工具沉淀。
• 培训转化体系。
• 标杆案例复制。
• 外部客户交付方法论。

ADR-005：第一批切入研发、市场和职能管理服务部门

日期：2026-06-10

背景

企业 Agent Harness 需要从真实高频场景切入，不能停留在抽象平台建设。第一批场景既要能证明内部降本增效，也要能沉淀为外部可复制方案。

决策

第一批切入部门为研发部门、市场营销部门和职能管理服务部门。

理由

• 研发部门适合验证 Codex、Claude Code 等代码 agent 能力，且有测试、PR、CI 等客观验证闭环。
• 市场营销部门内容和资料密集，适合快速体现 AI 对执行效率和输出质量的提升。
• 职能管理服务部门流程多、审批多、文档多，是组织运行成本集中区域。

影响

后续样板 workflow 优先选择：

• 研发：Issue 到 PR。
• 市场：资料到内容包。
• 职能：员工请求到工单/审批。

ADR-006：Web 任务工作台和企业微信是 AI 平权入口

日期：2026-06-10

背景

多数部门员工并不熟悉 Codex、Claude Code、SDK、API key、网络环境、海外订阅和工具配置。如果要求员工自己掌握这些，AI 能力会集中在少数技术人员手中，无法实现组织级平权。

决策

产品必须提供网页端任务工作台，并优先接入企业微信作为轻量入口、通知和审批通道。底层模型、runtime、工具、权限和网络复杂度由后端 harness 封装。

理由

• 员工使用门槛最低。
• 能承接自然语言、文件、表单、审批和业务控件。
• 符合目标企业现有协同习惯。
• 便于后端统一做权限、审计、评测和成本控制。

影响

后续前端不能只做聊天壳，而要设计任务工作台：

• 对话区。
• 文件空间。
• 业务控件。
• 任务状态。
• 审批确认。
• 证据和审计摘要。

ADR-007：Agent-to-Agent 网络参考 Zenoh 思想，但第一阶段先做逻辑 Agent Bus

日期：2026-06-10

背景

未来组织协作不只是人与 agent 的交互，还会出现 agent 与 agent 的协作。Agent 的组织结构会影响人的组织结构关系。

决策

Agent-to-Agent 通信参考 Zenoh 一类系统的思想，采用事件、命令、查询和产物传递的抽象。但第一阶段不强依赖 Zenoh，先在后端实现逻辑 Agent Bus。

理由

• 避免把所有 agent 写成点对点耦合接口。
• 支持部门 agent、专业 agent 和治理 agent 松耦合协作。
• 降低第一阶段基础设施复杂度。
• 保留后续迁移到 Zenoh、NATS、Kafka、Redis Streams 等基础设施的空间。

影响

后续需要定义：

• agent 命名和职责边界。
• message schema。
• event / command / query / artifact 类型。
• trace 和审计字段。
• 循环调用和冲突检测。

ADR-008：采用 Obsidian + GitHub 的团队知识库路线

日期：2026-06-10

背景

团队希望采用类似 Karpathy LLM Wiki 的方法，把微信群讨论、项目材料、网页资料、会议纪要和 Agent 输出沉淀为持续演化的团队知识库。团队规模约五六人，成员都是 AI 原生工程师。

决策

采用 Obsidian 作为团队知识库 IDE，GitHub 作为版本协作底座，MkDocs/Cloudflare Pages 作为正式教程发布渠道。

理由

• Obsidian 基于 Markdown 文件，适合 Agent 直接读写。
• GitHub 提供 PR、review、历史版本和多人协作。
• Karpathy LLM Wiki 方法强调 raw sources、wiki、schema、index、log，和当前工程化文档方式高度兼容。
• 团队是 AI 原生工程师，可以接受 Git 工作流。

影响

后续需要建立：

• team-vault 目录结构。
• ingest/query/lint/publish 四类 Agent 工作流。
• raw source 不可变规则。
• wiki 编译日志。
• 从 Obsidian 到 MkDocs 的发布流程。

ADR-009：项目升级为组织级 Agentic Knowledge Infrastructure

日期：2026-06-11

背景

当前 Harness 已经具备团队知识工程、MkDocs 文档站和 Obsidian vault 的基础。下一阶段需要从企业 Agent Harness 文档底座升级为组织级 Agentic Knowledge Infrastructure，并准备迁移到 VariAI/OrgReOrg 团队仓库。

参考 /home/ai/workspace/data_engineering 的私域搜索系统，组织知识能力不应停留在静态文档和聊天记录整理，而应支持文档解析、BM25 / 向量混合检索、Rerank、MCP 工具、Agentic Search、多轮阅读、证据引用和知识缺口识别。

决策

将项目定位升级为 OrgReOrg / Harness：组织级 Agentic Knowledge Infrastructure。

系统以企业微信、飞书和 Web 工作台作为统一交互入口，但不局限于聊天数据；通过 Agentic Search、主动信息收集、部门系统 Connector、MCP 工具层、权限化上下文视图和 Loop Engineering，把分散在 GitHub、财务系统、CRM、项目管理系统、文档系统、BI 等业务系统中的组织信息，持续转化为可检索、可调用、可授权、可审计的私域智能能力。

理由

• 企业微信和飞书适合做人机入口、通知、身份和审批确认，但不是完整业务数据源。
• 真实业务信息分散在部门业务系统中，必须通过 Connector 和权限化工具接入。
• Agentic Search 比一次性 RAG 更适合复杂组织问题，因为它支持多轮检索、深度阅读、交叉验证和缺口识别。
• 权限化上下文视图可以把统一知识与业务数据按用户、部门、项目、角色和任务裁剪给 Agent。
• Loop Engineering 可以把搜索、收集、权限和知识维护从隐式聊天行为变成可设计、可验证、可审计的工程循环。

影响

后续优先建设：

• 私域 Agentic Search 原型。
• 主动信息收集机制。
• Connector registry 和 MCP Tool Gateway。
• Permissioned Views / MVC 权限模型。
• Search Loop、Collection Loop、Permission Loop、Knowledge Maintenance Loop。
• 面向新仓库 OrgReOrg 的 README、导航和路线图。

ADR-010：MVP 先跑通企微入口与主动收集

日期：2026-06-12

状态：部分被 ADR-013 修正。OpenSearch / Elasticsearch 仍保留为规模化候选，但不再作为 P0 默认检索底座。

背景

OrgReOrg 的近期技术路线包含企业微信入口、Agentic Search、主动信息收集、知识外挂和 MVC 权限模型。当前阶段团队规模小，最重要的是先跑通真实任务闭环，验证智能体如何从已有知识搜索、发现缺口、主动询问相关人，并把补充信息沉淀为可复用知识。

决策

MVP 阶段优先建设：

• 企业微信入口和通知。
• 最小 Agentic Search。
• 知识缺口识别。
• 主动询问相关人。
• 补充信息以 knowledge_card 形式挂载到任务，再经 review 进入 vault 或 docs。

完整 MVC 权限模型不作为 MVP 前置条件，只保留最小只读、审计和高风险动作人工确认边界。

理由

• 企业微信是目标用户已有工作入口，能最快验证人机协同。
• 主动询问和“问谁”路由是产品创新点，应尽早验证。
• 补充信息来源复杂，先用 knowledge card 和 review 状态比一开始建复杂数据库更稳。
• 完整 MVC 权限模型需要真实数据对象、工具调用和审计记录作为输入，过早实现容易抽象失真。

影响

近期开发计划按企业微信 POC、最小搜索、主动询问、知识外挂、最小治理推进。后续出现跨部门、跨项目或敏感字段需求后，再启动完整 MVC 权限模型实现。

ADR-011：外部调研后调整检索与工具总线路线

日期：2026-06-12

背景

当前方案原本以 ES / embedding / MCP / Zenoh / 企微入口为主线继续做本地实验。用户指出，这容易在既定路线下自证，应该并行调研外部成熟方案、替代方案、开源项目和已知坑。

调研覆盖 Dify、RAGFlow、Open WebUI、AnythingLLM、LlamaIndex、Haystack、OpenSearch / Elasticsearch、Postgres + pgvector、Qdrant、Weaviate、Vespa、GraphRAG / LightRAG、MCP、OpenAI Agents SDK、LangGraph、Temporal、NATS、Kafka / Redpanda 和 Zenoh。

决策

• 保留 OpenSearch / Elasticsearch 作为第一候选检索底座，但第一批 benchmark 同时纳入 Postgres + pgvector / FTS。此口径已由 ADR-013 修正为：P0 默认 Postgres FTS/pgvector，OpenSearch/ES 为规模化候选。
• Dify、RAGFlow、Open WebUI、AnythingLLM 不作为核心替代平台；优先借鉴其 ingestion pipeline、复杂文档解析、external knowledge API、retrieval testing 和 agentic knowledge tools。
• MCP 只作为工具协议，不作为安全边界；所有 MCP server 先经过 Tool Gateway。
• Zenoh 不进入第一阶段核心 Demo 主线；第一阶段使用 JSON / Postgres registry + HTTP/gRPC。后续需要轻量服务发现时优先评估 NATS，需要审计回放时评估 Kafka / Redpanda，需要边缘或弱网络时再单独 spike Zenoh。
• 下一轮实验从 retrieval_failure_benchmark 升级为 retrieval_platform_benchmark，重点验证平台差异、权限过滤、增量更新、中文分词、rerank topK 和过期材料。

理由

• ES / OpenSearch 在 BM25、向量、hybrid、explain、索引生命周期和权限过滤上仍成熟。
• Postgres + pgvector / FTS 的 RLS、事务、一致性和低运维成本对小团队和 MVP 很有吸引力，不能忽略。
• Dify 和 RAGFlow 证明“入库流水线”和“复杂文档解析”是一等能力，但完整替代会削弱 Harness 对权限、审计、工具和组织模型的控制。
• Open WebUI 证明语义查询、精确 grep、按行读取应同时存在，不能只提供单一 RAG search。
• MCP 生态扩张很快，但工具描述、远程上下文暴露、token passthrough、SSRF、本地命令执行和动态工具列表都是安全风险。
• Zenoh 的 pub/sub/query/location transparency 思想有价值，但当前 Demo 的主要风险在检索、权限、工具治理和长流程恢复，过早引入会增加调试和运维复杂度。

影响

• 架构文档把 Zenoh 从第一阶段主线降级为后置 spike。
• MVP 的 M2 增加 OpenSearch/ES 与 Postgres+pgvector/FTS 的对照 benchmark。
• M4 前新增 Tool Gateway 安全实验，写操作默认 require approval。
• 风险驱动验证计划把 retrieval_failure_benchmark 改为 retrieval_platform_benchmark。
• 后续如果接入 Dify，优先通过 External Knowledge API 调用 Harness 自有检索服务，而不是迁移知识库。

ADR-012：采用多级上下文存储与渐进披露架构

日期：2026-06-12

背景

OrgReOrg / Harness 的底层 runtime 本来就基于 Codex SDK、Claude Code SDK、OpenAI Agents SDK 等成熟 agent runtime。它们已经具备读文件、搜索、调用工具、多轮探索、子任务分解和渐进披露能力。

如果 Harness 在上层直接建设一个单一 RAG 平台，可能会限制这些 runtime 的能力：Agent 只能看到 top-k chunk，而不能像研究员一样看目录、搜关键词、读原文、换检索策略、对比证据和发现缺口。

另一方面，组织数据规模会持续增长。大量业务数据、群聊、文档、项目记录和系统对象不可能都只靠 Markdown 手工维护，仍然需要入库、清洗、索引和权限过滤。

决策

采用多级上下文存储与渐进披露架构：

• L0 当前任务上下文：用户问题、当前计划、最近证据。
• L1 项目指令与工作记忆：AGENTS.md、CLAUDE.md、skills、规则。
• L2 编译后的 Markdown 知识：docs/、workspaces/variai/knowledge/wiki/、ADR、项目页。
• L3 搜索索引与检索缓存：BM25 / FTS / vector / metadata index。
• L4 原始材料与业务系统：企微、GitHub、CRM、财务、项目系统、BI。
• L5 人与组织网络：负责人、审批人、项目 owner、主动询问对象。

Context Router 不再被描述为“路由到某个搜索引擎”，而是判断当前任务应该优先使用哪一层，以及何时逐级下探。

理由

• Codex / Claude Code 的强项是按需搜索、读原文、调用工具和多轮探索，应优先利用，而不是用单次 RAG top-k 替代。
• Markdown wiki 适合承载稳定、可审查、可链接、可发布的团队知识。
• 搜索索引适合承载规模较大、变化较快、需要模糊召回的材料。
• 源系统适合保留权威事实，尤其是财务、CRM、项目状态和 BI 指标。
• 主动询问适合处理组织中尚未文档化、责任归属不清或证据不足的问题。

影响

• docs/ 和 vault/ 被明确为 L2 编译知识层，需要持续维护索引、链接、ADR 和项目页。
• OpenSearch/ES、Postgres+pgvector/FTS 被定位为 L3 检索缓存和索引层，不是最终事实源。
• Dify、RAGFlow、Docling、MinerU 等工具优先作为 L3/L4 入库、解析和检索组件评估。
• 后续 benchmark 需要新增“渐进披露优先、预入库 RAG 优先、分层混合”三类工作流对比。

ADR-013：Agentic Search P0 默认采用 Postgres，规模化保留 ES/OpenSearch

日期：2026-06-12

背景

ADR-011 在外部调研后把 OpenSearch / Elasticsearch 保留为第一候选检索底座，同时要求把 Postgres + pgvector / FTS 纳入第一批 benchmark。后续多级上下文讨论明确：底层 runtime 会基于 Codex SDK、Claude Code SDK 等成熟 agent runtime，应该利用其渐进披露、搜索、读原文和多轮验证能力；上下文体系也必须分级处理，不同层使用不同工具。

决策

P0 默认采用：

L1/L2：AGENTS / docs / vault / ADR 渐进披露
  -> L3：Postgres FTS + pgvector context document cache
  -> L4：业务系统 Connector / MCP 工具
  -> L5：主动询问负责人

规模化后再引入：

L3 scale adapter：OpenSearch / Elasticsearch hybrid search

纯 managed vector database 不作为核心默认方案。

理由

• P0 的主要风险是流程闭环、权限字段、生命周期、原文追溯和调试日志，不是大规模搜索集群吞吐。
• Postgres FTS + pgvector 的 RLS、事务、一致性和低运维成本更适合小团队先跑通 Agentic Search。
• OpenSearch / Elasticsearch 在 BM25、hybrid、RRF、rerank、explain 和大规模索引上仍然强，但需要在数据量和并发需求出现后再承担规模化 L3 adapter。
• Site/Knowledge 仍是 L2 知识生产与 review 层，不应被索引后端替代。

影响

• ADR-011 中“OpenSearch / Elasticsearch 作为第一候选检索底座”的口径被本 ADR 修正。
• M2 Agentic Search 的下一步是定义 SearchConnector contract，并先做 Postgres FTS/pgvector 的 P0 adapter。
• 后续真实 adapter benchmark 仍要对比 Postgres FTS/pgvector 与 OpenSearch/ES 的召回、延迟、ACL、删除传播和 rank log。

ADR-014：采用自试用自演进知识沉淀闭环

日期：2026-06-13

背景

Harness 的开发过程本身就是第一批真实使用场景。用户明确要求：自己持续丢资料、分享观点、讨论方案、质疑实验和指出流程问题的过程，都要按照 Karpathy LLM Wiki 式团队知识沉淀流程处理。

决策

采用自试用自演进闭环作为 Harness 开发和使用的全流程原则：

资料/观点/问题
  -> capture 到 workspaces/variai/evidence/inbox 或 workspaces/variai/evidence/raw
  -> compile 到 wiki、项目页或 ADR
  -> develop 最小实现、实验或流程修正
  -> test / benchmark / smoke test
  -> review 效果、成本、失败模式和风险
  -> publish 成熟内容到 docs
  -> 暴露的新问题进入下一轮 capture

理由

• Harness 的核心价值是把组织协作过程持续转化为可审查、可追溯、可发布、可复用的知识资产。
• 团队自己先按这套流程运转，能更早暴露入口、捕获、编译、review、发布、权限和成本问题。
• 高频人工补救动作可以反向沉淀为模板、脚本、workflow、Agent skill 或产品能力。

影响

• 项目讨论、外部资料、实验结论和流程摩擦都应进入 capture -> compile -> review -> publish -> verify 链路。
• AGENTS.md、vault 维护规则和协作流程页明确自试用原则。
• 后续实验报告需要记录效果、成本、失败模式和下一步，而不只记录“跑通了什么”。

ADR-015：引入轻量任务技能包作为 L1/L2 治理单元

日期：2026-06-13

背景

团队在讨论 Anthropic Lessons from building Claude Code: How we use skills 时，关注到 Claude Code Skills 的工程经验：Skill 更像可被 Agent 发现和使用的任务包，而不是单个 Markdown。当前 Harness 已有 L1 到 L5 多级上下文架构，但 L1/L2 之间还缺少一个更细粒度、可执行、可验证的组织单元。

决策

在 Harness 技术路线中引入轻量任务技能包作为 L1/L2 治理单元。

任务技能包用于承载高频、可复用、容易踩坑、需要验证的任务工作流。它不替代 docs/、vault/、ADR、L3 检索缓存、L4 Connector 或 L5 主动询问。

P0 阶段先不建设 marketplace，不新增复杂运行时。先用 repo 内文档、脚本、模板和 benchmark 形成可 review 的任务包规范。后续再按需要导出为 Claude Code Skill、Codex Skill 或企业微信 Agent workflow。

理由

• Anthropic 经验说明，高价值 Skill 通常沉淀 gotchas、验证方法、脚本和渐进披露结构。
• Harness 的“研用测一体”需要一个最小单元，把研究结论、使用流程、测试验证和失败反馈绑在一起。
• repo 内任务包能保持 Git review、版本管理和低运维成本。

影响

• L1/L2 不再只由 AGENTS.md 和 Markdown 页面组成；高频任务可以沉淀为任务技能包。
• 风险验证计划新增任务包膨胀、过期、误触发、脚本越权和 memory 污染等风险。
• 第一批候选包聚焦知识入库、文档发布、Agentic Search benchmark、ask_router review 和 Tool Gateway safety。

ADR-016：采用团队项目 Repo 作为产品 MVP 形态

日期：2026-06-13

背景

当前 OrgReOrg / Harness 仓库已经包含 vault/、docs/、实验脚本、测试、benchmark、ADR、维护日志、MkDocs 网站和研发进度总览页。用户明确要求：这个项目本身应该作为未来产品形态的一个 MVP / Demo。未来给一个团队、项目组或部门使用时，也应该能建立类似 repo，用来呈现项目状态、导航、进度、知识沉淀、实验报告和团队协作流程。

决策

采用“团队项目 Repo / Agentic Knowledge Workspace”作为 Harness 的最小产品形态之一。

当前 repo 同时承担三种角色：

• OrgReOrg / Harness 的研发仓库。
• 团队知识库和发布网站。
• 未来客户团队项目空间的最小 Demo。

最小产品形态包含 AGENTS.md、CLAUDE.md、workspaces/variai/site/project-progress.md、workspaces/variai/site/knowledge/*、vault/、scripts/、tests/、mkdocs.yml、CI、review 和 publish 链路。

理由

• 对团队或部门来说，最大问题不是缺少文档，而是缺少一个能持续同步状态、沉淀知识、验证实验和追溯决策的工作空间。
• Repo 提供版本、review、CI、发布和 Agent 可读文件系统，是小团队 P0 阶段最轻的产品容器。
• Vault 和 docs 区分了知识生产和稳定发布，适合研用测一体。
• 研发进度页把“当前状态”产品化，避免团队成员只能通过聊天记录理解项目。

影响

• 当前 repo 的结构调整应兼顾自用研发和未来产品 Demo 两个目标。
• 网站一级导航保留“研发进度”，作为未来团队空间的状态看板样板。
• 后续开发应逐步把手写 Markdown 看板升级为结构化数据驱动的看板。
• 未来产品可以提供项目空间模板：一键创建 repo、vault、docs、dashboard、benchmark 和 CI。

ADR-017：Framework 与 Workspace 边界，支持未来产品打包

日期：2026-06-13

背景

ADR-016 已经确认当前 repo 是未来团队项目空间的产品 MVP。用户进一步明确：repo 以后还会包含企业微信接口开发目录，并作为完整 MVP 跑通开发、验证、测试和运行。

但未来产品化或开源时，不能把整个 repo 原样打包。当前 repo 中有两类资产：

• 通用工具层、框架层、架构层和模板层。
• 当前项目的私域领域知识，也就是“如何开发 OrgReOrg / Harness 这个 Demo”。

未来某个部门或项目组使用产品时，它的领域知识会变成该部门自己的业务流程、项目状态、组织结构和私域材料。

决策

从当前阶段开始，按“可打包框架层”和“私域领域知识层”管理 repo 内容。

可打包层包括 Agent 工作规则和项目空间模板、vault/docs/dashboard 结构、SearchConnector、Tool Gateway、WeCom adapter contract、eval harness、benchmark 脚本、任务技能包规范、权限和审计规则。

私域领域知识层包括当前项目讨论、用户口述和会议材料、当前路线图和实验语境、真实组织结构、owner、通讯录、群聊和消息正文、客户/合同/财务/CRM/项目状态等业务系统事实。

短期不进行大规模目录重构。先通过文档、fixture 标识、目录 README 和 packaging.manifest.json 明确边界。等通用代码增长后，再把可打包层抽成 framework/、packages 或项目模板。

理由

• 当前 repo 需要继续保持研用测一体，过早拆目录会增加维护成本。
• 产品化的核心不是复制当前知识，而是复制让一个团队持续生产知识、验证实验和运行 Agent 工作流的底座。
• 私域知识必须留在使用方自己的 workspace 中，否则无法满足安全、合规和组织信任要求。
• 企业微信接入最容易混入真实组织数据，需要从接口目录建立隔离习惯。

影响

• 新增代码、fixture、docs 和 vault 内容时，需要标注或至少判断它属于通用层、混合层还是私域层。
• workspaces/variai/connectors/wecom/ 作为未来接口开发目录，只提交 adapter、schema、合成 fixture 和安全说明，不提交真实密钥、联系人、群聊或消息。
• 后续 dashboard generator、SearchConnector 和 eval harness 要优先设计为可抽包模块。
• 未来开源或交付前，需要增加打包检查：secret 扫描、私域内容扫描、导航替换、fixture 匿名化和 smoke test。

ADR-018：前置建立 framework/domain 基础结构与打包清单

日期：2026-06-13

背景

用户指出：如果等项目深入推进后再重构可打包框架层和私域领域知识层，成本会很高。当前代码量和目录依赖还小，应尽早把基础结构整理出来。

ADR-017 已经定义了框架与领域知识的边界，但只靠文档不足以约束后续开发。需要在 repo 里建立真实目录、机器可校验清单和 CI 检查。

决策

前置建立以下基础结构：

• framework/：未来可打包的通用框架层，包含 connectors、context、dashboard、evals、governance、policy、templates、workflows。
• workspaces/variai/registry/：当前 Demo 的领域知识索引，用于说明哪些内容未来打包时要替换。
• packaging.manifest.json：机器可读的打包边界清单。
• framework/governance/package_boundary.py 和 scripts/package_boundary_lint.py：边界校验模块和 CLI。
• CI 和本地检查脚本执行 package boundary lint。

现有 docs/、vault/、scripts/、tests/ 暂时不大搬迁，因为它们已经被 MkDocs、CI、实验脚本和网站导航引用。后续新增可复用代码优先进入 framework/；旧脚本稳定后逐步拆分迁入 framework/，scripts/ 保留 CLI wrapper。

理由

• 现在建立目录和 manifest 成本低，能避免后续大量脚本、fixture、docs 混杂后再重构。
• 机器可校验清单比纯文档更能约束协作者和 Agent。
• 保留现有路径可以避免一次性打断网站、vault 和 benchmark。
• framework/ 先成为新代码默认入口，再渐进迁移旧代码，风险更可控。

影响

• 新增可打包模块时默认进入 framework/。
• 新增或改变顶层目录边界时必须更新 packaging.manifest.json。
• CI 增加 python scripts/package_boundary_lint.py。
• workspaces/variai/registry/domain-inventory.json 作为当前 MVP 领域知识的索引，未来产品打包时用于剥离和替换。

ADR-019：迁移实现代码到 framework，scripts 只保留 wrapper

日期：2026-06-13

背景

用户明确表示当前阶段可以大刀阔斧重构，不必担心 Cloudflare Pages 发布配置和短期站点路径，因为项目仍处于早期且有 Git 版本控制。ADR-018 已建立 framework/ 和 domain/ 骨架，但如果实现代码继续堆在 scripts/，边界仍然只是形式。

决策

把第一批可复用实现迁入 framework/：

• framework/workflows/orgreorg_demo.py
• framework/workflows/ask_router_simulation.py
• framework/context/router_demo.py
• framework/evals/agentic_search_option_benchmark.py
• framework/evals/context_layer_benchmark.py
• framework/evals/ingestion_quality_demo.py
• framework/evals/retrieval_platform_benchmark.py
• framework/governance/vault_lint.py

scripts/ 只保留兼容 CLI wrapper，例如 python scripts/context_layer_benchmark.py --json 仍然可用。测试改为直接 import framework.*，确保真实实现不再依赖 scripts.*。

理由

• framework/ 必须承载真实实现，否则未来可打包边界没有工程约束力。
• 保留 scripts/ wrapper 可以不破坏既有命令、CI 和团队成员使用习惯。
• 测试直接引用 framework.*，能防止实现重新滑回 scripts/。
• 先迁移模块位置，不同时做大规模行为重写，风险更可控。

影响

• 后续新增功能默认在 framework/ 中实现。
• scripts/ 只作为 CLI、兼容入口或极薄 orchestration 层。
• 后续可进一步把 orgreorg_demo.py 内部的搜索、owner routing、knowledge card 渲染拆到 framework/context、framework/workflows 和 framework/templates。

2026-06-13 边界加固

• 本地 Markdown/token 搜索基础能力迁入 framework/context/local_search.py。
• 组织目录读取迁入 framework/connectors/org_directory.py。
• 其他 framework 模块不再从 framework.workflows.orgreorg_demo 导入 ROOT、tokenize、search 或 load_directory。
• package_boundary_lint 增加 Python import 边界检查，阻止 framework 层重新反向依赖当前 demo workflow。

ADR-020：采用结构化 project_status 生成研发进度页

日期：2026-06-13

背景

研发进度页已经成为团队成员进入网站后理解项目状态的主要入口。用户进一步明确：当前 repo 本身就是未来团队项目空间的 MVP，因此状态看板不应只是手工维护的 Markdown，而应该成为未来产品里“项目状态视图”的最小原型。

ADR-017 到 ADR-019 已经建立了 framework/ 和 domain/ 边界：生成器、校验器、模板属于可打包层；当前 OrgReOrg / Harness 的项目状态属于私域领域知识。

决策

采用结构化 project_status 数据生成 workspaces/variai/site/project-progress.md：

• 当前 Demo 的状态数据写入 workspaces/variai/registry/project-status.json。
• 通用生成器写入 framework/dashboard/project_status.py。
• scripts/generate_project_progress.py 只作为 CLI wrapper。
• CI 和本地检查通过 python scripts/generate_project_progress.py --check 防止页面与结构化状态不一致。

workspaces/variai/site/project-progress.md 仍作为网站一级导航入口，但它的内容来源变为结构化数据。以后团队更新项目状态，应优先更新 project-status.json，再生成页面。

理由

• 手写页面容易重复、过时，也不利于未来企微或 Web 复用同一份状态数据。
• 结构化状态数据能逐步扩展 owner、阻塞项、质量信号、实验报告、ADR、知识卡片和工具日志。
• 生成器在 framework/，当前数据在 domain/，符合产品化打包边界。
• CI 校验让状态看板成为工程流程的一部分，而不是一次性文档。

影响

• 修改研发进度页时需要先更新 workspaces/variai/registry/project-status.json。
• workspaces/variai/site/project-progress.md 由生成器覆盖，避免手工编辑生成结果。
• 后续 experiment_report、knowledge_card 和 SearchConnector 也应采用类似结构化数据 + 生成/校验的方式。
• 产品化时保留 framework/dashboard/project_status.py、页面模板和校验流程，替换 domain/<team-domain>/project-status.json。

ADR-021：先定义 SearchConnector contract，再实现真实检索 adapter

日期：2026-06-13

背景

ADR-013 已确定 P0 默认采用 Markdown 渐进披露 + Postgres FTS/pgvector，OpenSearch/ES 保留为规模化 adapter。后续要做真实 adapter 对照，如果没有统一 contract，业务逻辑、benchmark、权限过滤和 rank log 很容易被各个后端实现绑死。

同时，用户强调当前技术路线要基于 Codex / Claude Code SDK 的强 runtime 能力，不要把所有能力都压成单一 RAG。SearchConnector 的职责应是给 Agent 提供可解释、可审计、可替换的 L3 检索边界，而不是隐藏成一个不透明 top-k 文本接口。

决策

先在 framework/context/search_connector.py 定义 SearchConnector contract，再实现真实后端 adapter。

当前 contract 包含：

• ContextDocument
• SearchQuery
• EvidenceHit
• SearchResponse
• GapReport
• GapReceipt
• RankExplanation
• SearchConnector Protocol
• InMemorySearchConnector 合成参考实现

最小接口：

• search(SearchQuery) -> SearchResponse
• get_document(doc_id, allowed_scopes) -> ContextDocument | None
• report_gap(GapReport) -> GapReceipt
• explain(doc_id, SearchQuery) -> RankExplanation
• delete_or_supersede(doc_id, superseded_by=None) -> bool

理由

• Postgres 和 OpenSearch/ES 必须在同一 contract 下对照，才有可比性。
• 权限和 lifecycle 过滤必须在证据进入 Agent 上下文之前执行。
• Evidence 需要携带 source、scope、lifecycle、score_parts、rank_log 和 metadata，便于 debug、审计和引用。
• report_gap 是 Agentic Search loop 的一等产物，不能只返回空结果。
• 先有合成 adapter 和 contract tests，后续真实 adapter 可以复用同一 conformance test。

影响

• 后续 Postgres FTS/pgvector adapter 和 OpenSearch/ES adapter 必须实现同一 SearchConnector contract。
• retrieval_platform_benchmark 和 context_layer_benchmark 后续应迁移到 contract 之上，而不是各自写一套搜索模拟。
• context_document schema 已与 ContextDocument 投影链路对齐，后续 benchmark 和真实 adapter 应复用这条链路。
• Tool Gateway 应包裹 SearchConnector 工具调用，而不是让 Agent 直接自由访问后端数据库或搜索集群。

ADR-022：采用 workspace blueprint 作为产品化工作空间契约

日期：2026-06-13

背景

ADR-016 到 ADR-020 已经确认当前 repo 是未来团队项目空间的产品 MVP，并建立了 framework/、domain/、packaging.manifest.json 和结构化研发进度页。

用户进一步明确：当前仍处于早期，有 Git 版本控制兜底，可以大幅调整基础框架；但必须提前考虑未来打包时通用工具层和私域领域知识的解耦，否则后期再重构成本会很高。

已有 packaging.manifest.json 能说明哪些目录可打包、混合或私域，但还缺少一份“新团队、项目组或部门 workspace 应该如何初始化”的结构契约。

决策

新增 workspace.blueprint.json 作为 Agentic Knowledge Workspace 的机器可校验蓝图。

蓝图定义六层：

• Framework foundation：可原样打包的框架底座。
• Workspace operations：Agent 规则、CI、README、MkDocs、scripts、tests 等模板化运维层。
• Knowledge publishing：docs 和 vault 模板结构。
• Domain knowledge：当前团队、项目、实验、ADR 和输出，未来新 workspace 替换为自己的领域知识。
• Connector surface：adapter contract 可打包，真实配置和消息排除。
• Generated artifacts：站点构建输出等生成物，不作为源码打包。

同时新增：

• framework/governance/workspace_blueprint.py
• scripts/workspace_blueprint_lint.py
• scripts/workspace_blueprint_lint.py --dry-run
• scripts/workspace_blueprint_lint.py --scaffold-output <dir>
• tests/test_workspace_blueprint_lint.py
• framework/workspace.py 与 WorkspacePaths
• workspaces/variai/site/knowledge/workspace-blueprint.md

package_boundary_lint 同步调用 workspace blueprint lint。dry-run 会验证 copy_as_is、template_then_replace、create_empty 和 exclude_from_package 的源路径、manifest 覆盖、占位符替换和排除冲突。scaffold 生成器会把可打包底座复制到临时目录，生成 starter Site、Knowledge、workspace topology、project status、experiment registry、LoopRun 和 Semantic Review seed，并用快照检查避免带入 workspaces/variai/registry、site/ 或缓存文件。

理由

• 产品化要复制的是团队工作空间的结构和工具链，不是当前 OrgReOrg 的私域知识。
• 蓝图比自然语言说明更容易被 CI、Agent 和未来初始化工具执行。
• WorkspacePaths 把当前 repo 的 docs/、vault/、domain/<id>/ 路径从 framework 实现里参数化出来，避免可打包层继续硬编码 orgreorg-demo。
• 不立即大规模移动 docs/ 和 vault/，可以避免破坏 MkDocs 导航、Obsidian 链接、生成器和已有实验路径。

影响

• 新增顶层目录、workspace 层或初始化策略时，必须同步更新 workspace.blueprint.json。
• 新增 framework 模块如需读写 workspace 文件，应优先接受 WorkspacePaths 或显式路径参数。
• 历史口径中的 docs/、vault/ 内容已经迁到 workspaces/variai/site/、 workspaces/variai/knowledge/ 和 workspaces/variai/evidence/。当前 VariAI pilot 内容继续作为私域样板知识；未来打包时只保留结构、模板和可复用工具。
• 后续可以在蓝图基础上实现 workspace 初始化/打包 dry-run，检查 copy/template/create/exclude 的真实产物和冲突。

ADR-023：采用 experiment_report 作为实验导航唯一来源

日期：2026-06-13

背景

ADR-020 已经把研发进度页改为结构化 project_status 生成，后续又新增了结构化 experiment_report 索引来统一登记 P0 实验、Demo 和 benchmark。

在这个阶段，workspaces/variai/registry/project-status.json 和 workspaces/variai/registry/experiment-reports.json 同时维护了同一组实验名称、问题、结论和报告链接。短期可用，但会造成两个问题：

• 新增或修改实验时需要改两处，容易漏改。
• 研发进度页和实验报告索引可能对同一次实验给出不同结论。

用户明确当前项目早期可以重构，且有 Git 作为版本控制兜底，因此应趁结构还小先消除这类重复维护点。

决策

采用 experiment_report registry 作为实验导航的唯一来源。

具体规则：

• 当前 Demo 的实验注册表位于 workspaces/variai/registry/experiment-reports.json。
• project-status.json 不再手写 experiments 列表，只保留 experiment_registry.path。
• framework/dashboard/project_status.py 在渲染前从 registry 水合实验导航。
• framework/dashboard/experiment_report.py 提供 project_status_experiments_from_registry()，统一生成项目看板所需的实验名称、问题、结论和报告链接。
• 每个实验可以提供 project_status_conclusion，作为看板里的短结论；详细结论仍保留在实验报告明细中。
• CI 和本地检查继续用 experiment_report_lint --check-doc 与 generate_project_progress.py --check 防止生成页漂移。

理由

• 实验本身是研用测一体流程的一等对象，应该先进入实验 registry，再被网站索引、项目看板和未来企微/Web 工作台复用。
• 项目状态页是聚合视图，不应该复制实验事实。
• 这条规则符合未来产品形态：团队 workspace 中不同看板可以从同一份结构化领域数据生成。
• 早期消除重复字段，比后期实验数量变多后再迁移成本低。

影响

• 新增实验时优先更新 workspaces/variai/registry/experiment-reports.json，再生成 workspaces/variai/site/knowledge/experiment-reports.md 和 workspaces/variai/site/project-progress.md。
• project-status.json 只维护项目整体状态、里程碑、决策和下一步，不维护实验明细。
• 后续可继续给 experiment registry 增加 owner、freshness、cost、risk_level、last_run_at 和 blocked_by 字段，并同步投影到多个 dashboard。
• 产品化打包时保留通用生成器和 schema 规则，替换当前 demo 的私域实验 registry。

ADR-024：采用 task_skill_usage_log 作为任务技能包运行反馈源

日期：2026-06-13

背景

ADR-015 已经引入任务技能包作为 L1/L2 治理单元，task_skill_package_eval 也用合成样例验证了 guarded manifest 可以降低误触发、上下文膨胀和安全风险。

但离线 benchmark 只能证明一组设计样例可行，不能回答运行中的关键问题：

• 真实任务中哪些包被触发了。
• 哪些任务误触发或漏触发。
• 每次触发带来多少上下文 token。
• 哪些结果需要人工纠正。
• 纠正信号是否反向更新 manifest、gotchas 和 benchmark。

如果没有运行期日志，任务技能包会逐渐变成静态文档，无法支撑“研用测一体”的自演进闭环。

决策

新增结构化 task_skill_usage_log 作为任务技能包运行反馈源。

当前 Demo 的日志位于：

• workspaces/variai/registry/task-skill-usage-log.json

通用生成器位于：

• framework/dashboard/task_skill_usage.py
• scripts/task_skill_usage_log.py

发布页位于：

• workspaces/variai/site/knowledge/task-skill-usage-log.md

最小事件字段包括：

• task 摘要和 task_type。
• selected_package_ids。
• expected_package_ids。
• context_tokens。
• human_correction。
• correction_note。

P0 暂时允许手工记录本地研用测事件；接入企微或 Agent runtime 后，触发事件应自动写入同一 schema。

理由

• 任务技能包是否有效，必须看真实使用信号，而不只看设计文档。
• selected/expected 对照能同时暴露误触发和漏触发。
• context_tokens 能持续约束上下文膨胀。
• human_correction 是最直接的产品反馈，应反写到 manifest、negative_terms、gotchas 和 eval fixture。
• 日志只保存任务摘要、包 ID、token 和纠正备注，不保存原始聊天全文，降低知识库污染和隐私风险。

影响

• 更新任务技能包时，应同时查看 task_skill_usage_log 和 task_skill_package_eval。
• 新增任务包后，需要在 usage log 中观察触发次数、误触发、漏触发、人工纠正和 token 成本。
• workspaces/variai/site/knowledge/task-skill-usage-log.md 成为研发进度页和任务技能包页面的运行反馈入口。
• 后续可把 usage log 样例自动转成 task_skill_package_eval fixture，形成 run -> evaluate -> improve 的闭环。

ADR-025：采用本地 task_skill_runtime 作为企微前运行替身

日期：2026-06-13

背景

ADR-024 已经新增 task_skill_usage_log，但如果 usage event 只能手工写入，它仍然只是静态记录，不能验证运行时触发链路。

当前企业微信接口还未接入，线上 Agent runtime 也还没有稳定入口。为了继续推进“研用测一体”，需要一个本地、可复现、不依赖外部服务的运行替身：

任务输入
  -> manifest / negative_terms / status / verify guard
  -> 选择任务技能包
  -> 追加 usage event
  -> 生成 usage dashboard

决策

新增本地 task_skill_runtime：

• 实现：framework/task_skills/runtime.py
• CLI：scripts/task_skill_runtime.py
• 测试：tests/test_task_skill_runtime.py

本地 runtime 使用确定性规则：

• task_type 命中给高权重。
• trigger_terms 命中加分。
• negative_terms 命中则阻止触发。
• 只允许 active、有 verify_commands、没有 has_unsafe_script 的包被触发。
• 触发结果可追加到 workspaces/variai/registry/task-skill-usage-log.json。

同时把 usage log 中暴露的问题反写到 manifest：

• project_status_dashboard 增加 只读、只解释、不更新 dashboard 等 negative terms。
• harness_knowledge_ingest 增加 继续沉淀、进入团队知识库 等 trigger terms。

理由

• 没有企业微信入口时，仍然需要验证 Agent 任务触发、上下文成本和人工纠正链路。
• 确定性 runtime 可以在 CI 和本地稳定复现，不依赖模型输出。
• 运行替身能让 usage log 从手工表格变成可追加、可测试、可发布的数据流。
• manifest 反写让“用 -> 测 -> 改”成为工程行为，而不是只停留在文档原则。

影响

• scripts/check.ps1 增加 task_skill_runtime smoke test，但不追加日志，保持检查幂等。
• 后续真实企微/Agent runtime 应复用同一 usage event schema，而不是另建一套 telemetry。
• usage log 样例可以逐步转成 task_skill_package_eval fixture，形成真实失败样例回流。
• 本地 runtime 不是最终 Agent 编排层，只是企微接入前的 P0 可复现实验替身。

ADR-026：采用 orgreorg_demo 作为企微前本地 MVP 运行闭环

日期：2026-06-13

背景

P0 MVP 主线是：

用户输入
  -> 任务技能包选择
  -> 搜索 Site/Knowledge
  -> 证据不足时生成知识缺口
  -> 主动询问候选人
  -> knowledge card
  -> usage log / dashboard

企业微信入口尚未接入，但如果所有模块只以分散脚本存在，就无法验证这条链是否能端到端跑通。

决策

采用 orgreorg_demo 作为企微前本地 MVP runtime harness。

本轮改动：

• framework/workflows/orgreorg_demo.py 在搜索前接入 task_skill_runtime。
• Demo result 输出 task_type、selected_package_ids 和 usage_event。
• CLI scripts/orgreorg_demo.py 增加 --record-usage 和 --usage-log。
• scripts/check.ps1 增加幂等的 orgreorg_demo --json smoke test。
• tests/test_orgreorg_demo.py 覆盖任务包选择和 usage event 追加。

理由

• 未接企微时，也需要一个稳定的本地入口验证 MVP 主线。
• orgreorg_demo 已经包含 Site/Knowledge 搜索、gap、owner routing 和 knowledge card，最适合作为本地运行闭环。
• 接入 task_skill_runtime 后，任务技能包不再只是旁路 CLI，而是进入真实任务流。
• usage event 可回写 dashboard，让研用测循环有运行证据。

影响

• 后续企微/Web runtime 应复用 orgreorg_demo 暴露的数据结构和 usage event schema。
• orgreorg_demo 的 smoke test 成为本地 MVP 是否仍能跑通的基础检查。
• 后续要继续把回复解析、knowledge card review 和 SearchConnector adapter 接入同一条本地闭环。

ADR-027：采用 knowledge_card workflow 作为企微前回复与 review 替身

日期：2026-06-13

背景

P0 MVP 链路要求：

主动询问
  -> 被询问人回复
  -> knowledge card
  -> 人工 review
  -> vault/docs

企业微信入口尚未接入时，如果只生成 pending card，就无法验证回复是否能回到任务上下文，也无法验证未 review 内容是否会误入正式知识库。

决策

新增本地 knowledge_card lifecycle workflow：

• 实现：framework/workflows/knowledge_card.py
• 入口：scripts/orgreorg_demo.py --reply-card
• 入口：scripts/orgreorg_demo.py --reply-card --reply-text
• 入口：scripts/orgreorg_demo.py --review-card
• 入口：scripts/orgreorg_demo.py --promote-card
• 测试：tests/test_knowledge_card_workflow.py
• 文档：workspaces/variai/site/knowledge/knowledge-card-review-flow.md

本地规则：

• pending card 可以追加模拟回复，但不能 promote。
• approve 会把 review_status 改为 reviewed，并校验 promote 路径。
• reject 和 needs_changes 不能 promote。
• promote 目标只能在 workspaces/variai/knowledge/wiki、workspaces/variai/knowledge/projects 或 docs 下。
• 已 review 的 card 不允许继续追加回复，避免静默篡改正式结论。

理由

• 这补齐了企微前本地 MVP 的“回复 -> review -> 提升”链路。
• Markdown card 继续符合 Karpathy LLM Wiki 与渐进披露流程，可 review、可 diff、可回滚。
• 路径白名单和 review gate 能防止未确认材料直接污染正式知识库。
• 后续企微/Web runtime 可以复用同一 workflow，而不是重建一套业务规则。
• 结构化回复解析已先在本地落为 parse_ask_reply_text / append_parsed_reply_to_card，真实企微 adapter 只需要补身份、签名、消息 ID、会话 ID 和可靠投递。

影响

• orgreorg_demo 现在是本地 MVP runtime harness，而不只是搜索/gap/ask demo。
• 后续企微 callback 应输出或映射到 answer、responder、permission_scope、confidence、source_uri 和 better_owner，再调用同一 workflow。
• promote 后的页面后续应投影为 ContextDocumentRecord，进入 SearchConnector adapter。
• 本轮 smoke 发现“付款状态”曾误触发 project_status_dashboard，已收紧任务类型判断并加回归测试。

ADR-028：将 reviewed knowledge card 投影到 ContextDocumentRecord

日期：2026-06-13

背景

ADR-027 已经让本地 MVP 跑通：

pending card
  -> reply
  -> review
  -> promote to vault/docs

但如果 promote 后只停留在 Markdown 文件，L3 检索 adapter、rank log、权限过滤和 conformance test 仍然无法验证这条新知识是否能进入标准检索路径。

决策

为 knowledge_card workflow 增加 ContextDocumentRecord 投影：

• promoted_card_to_context_document() 只接受 review_status: reviewed 且已经 promote 的 card。
• 投影读取 promoted markdown，生成稳定 document_id、source_hash、chunk、owner、permission_scope 和 metadata。
• source_uri 指向 promoted markdown，metadata 保留 source card 路径、task_id、responder 和 reviewer。
• task_only / restricted card 投影时保留 field mask，避免进入无范围约束的长期检索。
• CLI 增加 scripts/orgreorg_demo.py --context-document-card <card> --json。
• 测试用 SqliteFtsSearchConnector 验证 reviewed/promoted card 可以进入 SearchConnector 检索。

理由

• 这把 L2 Markdown review 层和 L3 检索缓存层接上，避免 review 后知识只存在于发布文件里。
• ContextDocumentRecord 是当前入库清洗、权限、lifecycle 和 SearchConnector 的统一契约。
• 真实 Postgres FTS/pgvector 和 OpenSearch adapter 后续只需要消费同一投影结果。

影响

• 未 review 或未 promote 的 card 不能投影，继续防止未确认材料污染检索。
• 本地 reindex queue 原型已经接入同一 workflow，用于把 ready card 处理成本次增量索引。
• 后续仍需要把 delete/supersede 传播、PII/field mask 建议和真实 Web/企微 runtime 接入同一队列，而不是直接写入正式索引。

ADR-029：采用本地 knowledge card reindex 替身连接 L2 review 与 L3 检索

日期：2026-06-13

背景

ADR-028 已经支持单张 reviewed/promoted card 投影为 ContextDocumentRecord。但 MVP 运行时需要的是可复跑的索引刷新流程：

workspaces/variai/evidence/inbox reviewed/promoted cards
  -> scan
  -> project ContextDocumentRecord
  -> build local SearchConnector index
  -> search

如果没有批量 reindex 替身，review 后的新知识无法进入统一搜索路径，只能靠人工记住单条投影命令。

决策

新增本地 knowledge card reindex workflow：

• reindex_knowledge_cards() 扫描 workspaces/variai/evidence/inbox/**/*knowledge-card*.md。
• 只索引 reviewed 且已经 promote 的 card。
• pending、reject、needs_changes 和 reviewed-but-unpromoted card 会被跳过。
• promoted markdown 先投影为 ContextDocumentRecord，再转成 SearchConnector.ContextDocument。
• 本地索引用 SqliteFtsSearchConnector 作为 CI-safe 替身。
• CLI 增加 scripts/orgreorg_demo.py --reindex-cards --json。
• CLI 增加 scripts/orgreorg_demo.py --search-card-index <query> --allowed-scope team --json。

理由

• 这让 L2 Markdown review 结果可以批量进入 L3 检索缓存。
• SQLite FTS 替身可在 CI 和本地稳定复现，不依赖外部 Postgres/OpenSearch 服务。
• 同一投影 contract 后续可替换为 Postgres FTS/pgvector 或 OpenSearch adapter。

影响

• 当前 repo 没有真实 promoted card 时，reindex 输出 indexed_count=0 是正常状态。
• 当前已新增本地 JSON reindex queue 原型：card review/promote 后可以进入 workspaces/variai/registry/knowledge-card-reindex-queue.json，ready item 可被处理成本次增量索引。
• 后续需要把这个 JSON queue 替换为可恢复 worker / Postgres table，并接真实 Postgres/OpenSearch adapter。
• 后续真实 adapter 要继承同样的跳过规则、permission_scope 过滤和 rank_log 输出。

ADR-030：采用本地 Tool Gateway safety harness 作为 MCP/Connector 安全门禁

日期：2026-06-13

背景

ADR-011 已经明确 MCP 是工具协议，不是安全边界。随着 SearchConnector、knowledge card reindex、企微 adapter 和未来业务系统 Connector 逐步出现，如果 Agent 可以直接调用 MCP server 或 Connector，权限、审批、输出净化和审计会被分散到各个工具实现中。

完整 MVC 权限模型仍然后置，但 Tool Gateway 的最小安全边界不能后置。否则后续真实 Connector 一旦接入，写操作、外连 URL、动态工具列表和工具输出污染都会成为返工点。

决策

新增本地 tool_gateway_safety_harness，作为 MCP / Connector 前的最小安全门禁：

• 工具必须在 allowlist 中固定 tool id、version、risk_level、allowed_scopes 和 allowed_actions。
• 请求必须携带 trace id、user、session 和 schema hash。
• schema hash 不匹配直接拒绝。
• 用户 scope 不满足工具策略直接拒绝。
• R4 高风险动作必须 require approval；R3 可写动作可以先降级为 draft-only。
• fetch / URL 类工具必须做 egress allowlist 和内网/metadata host 拦截。
• 工具输出进入模型前先脱敏；审计日志也保存脱敏后的 arguments 和 output。
• 本地 fixture 覆盖 9 个合成 case，并进入实验 registry、研发进度页和 CI 检查。

理由

• 这能在真实企微、GitHub、财务、CRM 等 Connector 接入前先固定共同安全语义。
• schema hash 和 allowlist 能降低动态工具列表、工具描述漂移和错误版本工具被调用的风险。
• draft-only / require-approval 把“可撤销草稿”和“正式高风险动作”分开，避免一开始就实现完整审批系统。
• 输出净化和审计净化同等重要，审计日志不能成为密钥、cookie、password 或 private key 的新泄漏面。

影响

• SearchConnector、knowledge card reindex 和后续企微 Connector 应逐步包到 Tool Gateway 调用路径后面。
• 后续真实 MCP server adapter 必须补 schema、timeout、错误码、输出 schema 和 source-system permission contract test。
• MVC 权限模型仍然后置，但 permission leak test 要继续验证内容、路径、owner 和对象存在性都不泄露。

ADR-031：将 SearchConnector 作为 Tool Gateway 后面的检索工具族

日期：2026-06-13

背景

ADR-021 定义了 SearchConnector contract，ADR-030 定义了 Tool Gateway 最小安全门禁。下一步风险是：即使 SearchConnector 自身通过了 adapter conformance，如果 Agent 或 workflow 仍然直接调用 connector 对象，schema hash、scope escalation、审计和输出净化仍然绕过 Tool Gateway。

SearchConnector 是第一个已经稳定的数据工具族，适合作为 Tool Gateway 接入样板。

决策

新增 SearchConnectorToolGateway adapter，把检索能力暴露为三类工具：

• context.search
• context.get_document
• context.report_gap

这些工具必须先通过 Tool Gateway，再执行实际 connector 方法。当前本地 conformance 覆盖：

• team 用户正常搜索。
• 请求中的 allowed_scopes 超过用户 scope 时拒绝。
• 故意不安全的 connector 返回 restricted hit 时，gateway 后置过滤。
• 故意不安全的 get_document 返回 restricted document 时，gateway 抑制输出。
• report_gap 通过 gateway 审计并记录缺口。

理由

• SearchConnector 自身仍要做权限和 lifecycle 过滤，但 Tool Gateway adapter 提供第二道边界。
• allowed_scopes 不能由 Agent 自己扩大，必须是用户 scope 的子集。
• 对模型和审计暴露的 safe output 不包含 source_uri，降低路径、owner 和对象存在性泄漏风险。
• 这个模式后续可复用到 Postgres/OpenSearch adapter、knowledge card reindex/search 和企微 Connector。

影响

• 后续真实 adapter 不仅要通过 search_connector_conformance，还要通过 search_tool_gateway_conformance。
• knowledge card reindex/search CLI 应切到 SearchConnectorToolGateway，避免本地索引绕过工具门禁。
• permission leak test 需要继续扩展 rank_log、owner、path 和 source_uri 泄漏检查。

ADR-032：将 Knowledge Card reindex/search 纳入 Tool Gateway

日期：2026-06-13

背景

ADR-027 到 ADR-029 已经跑通无企微条件下的 knowledge card 生命周期：主动询问补充信息、人工 review、promote 到 vault/docs，并投影为 ContextDocumentRecord 后进入本地 SQLite FTS SearchConnector。

ADR-030 和 ADR-031 又把 Tool Gateway 和 SearchConnector Tool Gateway 建起来。剩下的风险是：orgreorg_demo --reindex-cards / --search-card-index 如果继续直接调用本地 reindex/search，就会绕过 Tool Gateway，导致本地 Demo 的核心知识外挂路径和未来真实工具路径不一致。

决策

新增 KnowledgeCardToolGateway：

• knowledge_card.search：先通过 Tool Gateway，再内部调用 context.search，实际检索继续复用 SearchConnectorToolGateway。
• knowledge_card.reindex：作为治理动作，只允许具备 restricted scope 的用户触发。
• orgreorg_demo --reindex-cards 和 --search-card-index 切到 gateway safe output。
• 新增 conformance：第一轮 5 个 case 覆盖 team search、scope escalation、restricted card 泄漏、reindex 权限和 safe output 不泄漏路径/ID；第二轮扩展到 8 个 case，继续覆盖对象 ID、owner、source_uri、路径、rank_log 存在性计数和 reindex 错误路径泄漏；第三轮扩展到 10 个 case，覆盖本地 reindex queue safe output 和 ready item 增量处理；第四轮扩展到 11 个 case，覆盖 queue processing 的 OntologyToolGateway required scopes gate；第五轮扩展到 12 个 case，覆盖 queue worker 前后态写入 ontology registry 且 safe output 不泄漏 object id；第六轮扩展到 14 个 case，覆盖 review/promote 前置 OntologyToolGateway gate 和 pending/reviewed/promoted registry lifecycle。
• 新增本地队列状态：workspaces/variai/registry/knowledge-card-reindex-queue.json 作为当前 MVP 的 JSON 队列原型。

理由

• knowledge card 是主动询问后进入知识库的主要外挂形式，不能绕过工具安全边界。
• reindex 可能暴露全局卡片数量、失败路径、skipped card 和对象存在性，因此不应对普通 team 用户开放。
• search 的权限语义应复用 SearchConnector Tool Gateway，而不是另写一套过滤逻辑。
• safe output 给 Agent 使用，不需要暴露 source path、card path、promoted path、owner 或 reviewer。

影响

• 无企微条件下，MVP 的“主动询问 -> review -> 知识外挂 -> Agentic Search”路径更接近真实产品形态。
• 后续企微回复解析接入后，应复用同一 knowledge card gateway conformance。
• 本地 reindex queue 已能表达 waiting_for_promote / ready_for_reindex / indexed / error，并把 ready card 处理成本次增量索引。
• 后续需要把本地 JSON queue 升级为可恢复 worker / Postgres table，并接真实 Postgres/OpenSearch adapter。

ADR-033：采用 Workspace Topology 作为组织私域路由和隔离契约

日期：2026-06-13

背景

Framework / Workspace 拆分后，domain/ 不能只是当前项目资料目录。未来 Framework 会交付给一个组织，这个组织下面有部门、课题组、项目、员工和具体任务。个人入职/报销、部门报销政策、项目研发知识都属于私域，但它们的 owner、权限、上下文库和路由方式不同。

如果不在早期建模，后续 Agentic Search、主动询问、知识外挂和权限视图会把所有私域知识混成一个库，导致路由不准、权限边界不清、产品打包困难。

决策

采用 domain/<domain-id>/workspace-topology.json 作为组织私域拓扑契约，当前最小字段包括：

• organization
• scope_taxonomy
• departments
• people
• projects
• tasks
• context_libraries
• routing_rules
• permission_views
• demo_cases
• isolation_requirements

同时新增：

• framework/governance/workspace_topology.py
• scripts/workspace_topology_lint.py
• framework/evals/workspace_scope_eval.py
• scripts/workspace_scope_eval.py
• workspaces/variai/site/knowledge/workspace-topology.md
• workspaces/variai/site/knowledge/workspace-scope-eval.md

当前 demo 必须至少覆盖三类验收场景：

• personal：员工入职与首次报销。
• department：财务部门报销政策。
• project：当前 OrgReOrg Framework MVP 开发。

理由

• 同一套 Framework 必须能服务公司内不同粒度的协同工作，而不是只服务当前项目。
• 路由可以生成候选上下文库，但最终调用和输出必须受 permission view 约束。
• 权限边界不能只靠 prompt 描述，必须有可校验 topology、可运行 eval 和 Tool Gateway。
• 产品化时 Framework 可以带走，workspaces/variai/registry/ 必须被替换为客户组织自己的 topology 和私域知识。

影响

• workspace scaffold 现在会创建 organization/、departments/、people/、projects/、tasks/、context-libraries/、routing/、permission-views/。
• SearchConnector Tool Gateway 已支持已认证 person:*、dept:*、project:* namespaced scopes。
• rank_log 被纳入泄漏面，safe output 只保留安全计数字段。
• 后续真实 Context Router、Postgres/OpenSearch adapter 和 Ask Router 都要接入 Workspace Scope Eval。

ADR-034：Ask Router route 必须经过 OntologyToolGateway

日期：2026-06-13

背景

Ask Router 是主动询问链路的实际动作入口。此前它已经能根据 knowledge gap 选择 owner、生成消息、处理问错人反馈和节流，但如果 route 直接产生 ask message，就会绕过 Workspace Topology 中的对象、规则、动作和写回约束。

决策

• 新增 route_ask_request_guarded，在执行 route_ask_request 前先用 OntologyToolGateway 验证 action-ask-people-owner。
• Ask action 必须满足 required scopes、rule 覆盖、person/task lifecycle 和 audited writeback。
• 允许后把 person/task 状态写入 ontology-object-registry.json；拒绝时不运行 route，也不产生 registry 写入。
• safe output 只暴露 action、blocked、registry event count 和路由摘要，不暴露 owner、object id、message body 或 missing_info。

影响

• No-WeCom MVP Demo 的 ask、review/promote、reindex queue 均走过 ontology gate 和 registry。
• Ontology Tool Gateway Conformance 扩展到 10/10，新增 personal、department、project 三类 ask action case。
• 后续企微 adapter 只替换 delivery/callback，不改变 Ask Router guarded route 的治理边界。
• permission leak test 下一步继续覆盖审计事件、worker retry 事件和真实增量 adapter 状态。

ADR-035：Ask Router binding 进入 Workspace Topology 配置

日期：2026-06-13

背景

ADR-034 让 Ask Router route 先经过 OntologyToolGateway，但 personal、department、project 三类 ask binding 仍主要在代码里表达。这样会削弱 Framework / Workspace 解耦：未来换成客户组织时，Framework 不应该知道某个部门、项目或任务应该绑定哪些 object state、ask action 或 throttle 对象。

决策

• 在 domain/<domain-id>/workspace-topology.json 新增 ask_router_bindings。
• 每条 binding 声明 scope_type、action_id、object_ids、fallback / delivered object states、throttle_object_id、match_context_library_ids 和 match_task_ids。
• workspace_topology_lint 校验 binding 的 scope、task、context library、ontology action、ontology object 和状态映射引用。
• route_ask_request_guarded 优先从 topology 读取 binding；代码里的默认 personal/department/project mapping 只作为兼容兜底。

影响

• Framework 继续保持通用，客户 domain 可以通过 topology 配置主动询问 route，而不是修改 Python 代码。
• No-WeCom MVP 的 personal、department、project 三类 ask route 仍通过同一 OntologyToolGateway 和 registry 写回路径。
• 下一步应把企微通讯录、delivery/callback 和外部 Connector action 接到当前 topology binding 与 owner registry contract 后面。

ADR-036：采用 owner registry contract 连接主动询问与组织目录

日期：2026-06-14

背景

Ask Router 需要 owner profile 才能把 knowledge gap 转成“应该问谁”。此前本地 Demo、仿真和端到端 smoke 分别直接读取 org-directory.json 或显式传入 people，这会让真实企微通讯录接入时出现两类风险：

• 企微 adapter 可能把“找人”逻辑写进消息层，绕过 Ask Router、OntologyToolGateway 和 registry。
• 没有企微接口时，Workspace Topology 明明已经声明了 people、departments、tasks 和 context_libraries owner，却不能独立驱动主动询问。

决策

• 新增 load_owner_registry() 作为 Ask Router 的 owner 来源 contract。
• 显式组织目录存在时优先读取 workspaces/variai/knowledge/system/org-directory.json。
• 显式目录不存在时，从 workspace-topology.json 派生 owner profiles，并自动补充 synthetic requester。
• route_ask_request_guarded() 在未传入 people 参数时自动从 topology 加载 owner registry。
• orgreorg_demo、ask_router_simulation 和 No-WeCom MVP Demo 改为使用统一 owner registry contract。

理由

• 主动询问应该依赖稳定 owner registry，而不是依赖某个具体通讯录 SDK。
• Workspace Topology 已经是组织私域事实的源头之一，P0 阶段可以作为企微前的本地 owner fallback。
• 真实企微 adapter 后续只需要输出同一类 owner profile，Ask Router 不需要重写。
• 显式目录优先可以允许真实部署覆盖 topology fallback，同时保持本地测试可运行。

影响

• 无企微条件下，personal、department、project 三类 Ask Router guarded route 可以只靠 topology 生成 owner profile。
• 本地仿真和 No-WeCom smoke 使用同一 owner registry contract，减少 Demo 与未来实现分叉。
• 企微同学后续接通讯录时，应把人员、部门、别名、联系方式和可见范围写入 owner registry adapter；消息投递层只负责 delivery/callback，不决定 owner 选择。

ADR-037：采用 Evidence / Ontology / Runtime Projection 作为项目主抽象

日期：2026-06-14

背景

ADR-012 曾把上下文体系描述为 L0-L5 多级存储：当前任务、项目指令、Markdown、检索索引、源系统和人与组织网络。这个模型对运行时渐进披露有帮助，但容易把“知识形态”和“访问顺序”混在一起，尤其会误导读者以为原始资料属于更高的 L4，而 Markdown、Skill、元数据和权限规则只是并列层。

用户进一步指出，项目真正需要沉淀的是本体论意义上的组织语义操作模型：原始资料要保真保存；从资料中提炼出的不只是摘要，而是元数据、对象、关系、规则、知识制品、Skill、Workflow、权限视图、动作和 writeback；运行时再按用户、任务和权限投影最小充分上下文。

决策

项目主抽象重构为三块：

• Evidence：原始证据层，保存企微、会议、文档、链接、代码、附件、业务系统对象和外部资料快照，保留 provenance、权限、hash、版本和回查路径。
• Ontology：本体层，统一建模 metadata、object、relationship、rule、artifact、skill、action、writeback、permission view 和 lifecycle。
• Runtime Projection：运行时投影层，根据当前用户、任务、权限和本体状态，组合最小充分上下文，并通过 SearchConnector、Tool Gateway、Ask Router、Connector、LoopRun 和 dashboard 执行与审计。

ADR-012 的 L0-L5 不再作为知识形态总模型，只保留为运行时渐进披露路径，并改名为 D0-D5：当前任务、入口索引、稳定知识制品、检索投影、证据读取、主动补充。

理由

• 原始资料必须统一归入 Evidence，不能一会儿是 raw、一会儿是 L4。
• Markdown、ADR、实验报告和 Skill 都是本体对象或制品，不应被描述成低层缓存。
• SearchConnector、Postgres/OpenSearch、MCP 和企微消息是运行时投影的实现，不是事实源。
• 本体层可以把权限、review、provenance、writeback、Skill 使用日志和实验报告放到同一个语义框架里。
• 这个抽象更适合解释产品目标：在当前任务和权限下投影最小充分上下文，而不是追求全量召回。

影响

• workspaces/variai/site/project-progress.md 必须以 Evidence / Ontology / Runtime Projection 三段展示研发进度。
• workspace-topology.json 从 context library registry 升级为轻量 ontology contract，并开始声明 metadata、artifact、skill 和 provenance 扩展字段。
• 任务技能包被重新定位为本体层的可执行知识对象。
• SearchConnector、Tool Gateway、Ask Router、No-WeCom Demo、Context Management Eval 和 Search Adapter State Benchmark 都归入 Runtime Projection 验证。
• 后续 Roadmap 和实验计划必须说明每项工作验证的是 Evidence、Ontology 还是 Runtime Projection。

ADR-038：采用 Evidence Registry 作为原始证据源契约

日期：2026-06-14

背景

ADR-037 已经把项目主抽象校准为 Evidence / Ontology / Runtime Projection。但当前实现中，ContextDocumentRecord 更靠近 Runtime Projection，负责被 SearchConnector 检索的规范化文档；workspaces/variai/evidence/raw/ 和 workspaces/variai/evidence/inbox/ 虽然保存了材料，但缺少统一机器契约来证明原始 source snapshot、hash、临时外链状态、PII/mask 和下游 artifact 关系。

如果没有这层 contract，外部临时链接、企微消息、会议、附件、业务系统对象和代码包进入知识库后，很难审计“这个结论最早来自哪里”。

决策

采用 domain/<domain-id>/evidence-registry.json 作为 P0 Evidence source registry。

每条 source 至少记录：

• source type、source system、source uri 和 source statuses。
• source snapshot path 和 sha256 hash。
• permission scope、review status、retention policy 和 runtime paths。
• PII flags、field mask、attachment manifest。
• downstream ontology artifact 或 runtime projection 引用。
• provenance 信息，包括临时外链封口状态和搜索关键词。

新增 framework/governance/evidence_registry.py 和 scripts/evidence_registry_lint.py，将 Evidence Registry 纳入 CI 和本地检查。

理由

• Evidence 层需要保真和可追溯，不能只依赖 ContextDocument 或 Markdown 摘要。
• 临时微信公众号、签名下载、分享链接不能作为长期 source uri；应记录稳定镜像、搜索关键词和 no-further-search 状态。
• task_only / restricted source 必须在进入本体或检索投影前声明 PII 或 field mask。
• 下游 docs、wiki、ADR、实验报告、knowledge card 和 context document 必须能反查原始 evidence。

影响

• 当前 demo 新增 workspaces/variai/evidence/registry/evidence-registry.json。
• Workspace scaffold 会生成最小 Evidence Registry seed。
• CI 新增 python scripts/evidence_registry_lint.py。
• Evidence 主线进度从“待补 schema”推进为“registry schema/lint 已落地，等待真实 connector 写入”。
• 后续 ingestion、Connector Callback Ledger、企微消息和业务系统 connector 应先写 Evidence Registry，再投影到 ContextDocument 或 Ontology artifact。

ADR-039：企微先采用 Bot WS 最小通道，并并行准备全量接入

日期：2026-06-15

状态：历史阶段决策。2026-06-16 起，正式企微接入路线由 ADR-040 取代；本 ADR 只保留 P0 Bot WS smoke 的背景、验收和边界。

背景

VariAI 已创建企业微信智能机器人，当前连接方式为长连接，管理员已提供 Bot ID 与 Secret。用户已被设置为企业微信超级管理员，后续可以直接在企业微信后台配合完成自建应用、可见范围、回调和文档权限设置。

PR #48 和 Hermes Agent 的 WeCom 实现提供了通道调研、字段映射和回调处理参考，但当前项目已经重构到 workspaces/variai/，不能直接沿用旧 vault/、旧 wecom/ 路径或 Hermes gateway 抽象。

决策

以下为 2026-06-15 P0 阶段决策。2026-06-16 起，正式路线由 ADR-040 重新定义。

• P0 先采用企业微信 AI Bot 长连接跑最小通道：收到单聊或群 @ 后固定回复 1。
• 通道层只负责把企业微信 payload 投影为内部 message event，不在通道层直接接 LLM、上下文检索或文档写入。
• P1 并行准备公网服务器与自建应用，用于 URL 回调、应用消息、通讯录同步、文档/日报 API 和更完整事件能力。
• P2/P3 再评估会话内容存档。团队“全量消息进入知识库”不能靠普通 Bot WS 或自建应用回调完成，必须走合规存档范围、员工告知和 SDK 拉取链路。

理由

• Bot WS 是当前最短可验证路径，不依赖公网入站、域名、HTTPS 证书、URL 验证或可信 IP。
• 固定回复 1 可以把企业微信通道问题与 Agent、上下文、权限和工具调用问题隔离。
• 当前 Framework 以 Python 为主，先实现 Python smoke runner 能直接进入现有测试和 CI；如果后续发现 Python 裸 WS 与官方 SDK 行为不一致，再把通道进程切到 Node/TypeScript。
• 全量聊天记录属于合规归档问题，不是给机器人多开普通权限的问题。

影响

• workspaces/variai/connectors/wecom/contracts/aibot-ws-channel.md 成为 AI Bot WS 字段映射、回复、并发和隐私边界的历史 smoke/临时入口契约。
• scripts/wecom_bot_ws_smoke.py 成为最小真实通道 smoke 入口，凭证只允许从环境变量读取。
• workspaces/variai/knowledge/projects/企微全量接入开发计划.md 作为明天企微全栈开发计划。
• 真实回调跑通后，只能提交脱敏 synthetic fixture，不提交真实 Bot ID、Secret、用户 ID、群 ID 或聊天正文。

ADR-040：企微正式接入采用主动沉淀 MVP 与会话存档增强分层

日期：2026-06-16

状态：有效，取代 ADR-039 中的正式路线判断，并修正同日早期“会话内容存档是当前 MVP 主线之一”的表达；ADR-039 仅保留为 P0 Bot WS smoke 的历史决策。

背景

ADR-039 解决的是“没有公网入口前如何尽快验证企业微信通道”的问题。2026-06-16 已经完成 Bot WS P0 smoke：单聊机器人、群里 @机器人、固定回复和 reply ack 均已验证。随后团队明确目标不是只让机器人能回复，而是要围绕企业微信收集部门协作证据、维护日报/文档、同步上下文，并最终支持团队知识库建设。

新的产品路线判断进一步收敛：

• 企业微信会话内容存档主要覆盖普通聊天历史、全量被动采集、历史回溯和合规审计，只是企微上下文的一类来源。
• 当前 MVP 可以退而求其次，把“需要知识库沉淀积累的消息”定义为团队成员主动 @Bot、私聊 Bot、转发给 Bot，或写入指定文档/日报入口。
• 这意味着当前 MVP 不需要先开通会话内容存档。智能机器人 Bot（生产 Bot URL 回调，开发/回归 Bot WS）+ 自建应用 API/回调，已经能覆盖企微作为团队知识库入口的大部分主动能力。
• 企业微信智能机器人 Bot 本身有两种连接方式：Bot WS 长连接和 Bot URL 回调。二者是同一个智能机器人消息入口的两种接入方式，不是两条业务能力路线。
• 自建应用回调/API 承接通讯录、部门成员、权限、文档/日报、会议、应用消息和主动提醒，但不替代普通聊天历史采集。
• 不 @ 也采集普通群聊/单聊、历史消息、媒体下载、seq/cursor checkpoint 和合规归档，仍必须单独走会话内容存档或等价企业会话内容能力，并满足合规告知、审批、范围控制和 SDK 拉取要求。
• 2026-06-16 后续补充的飞书自研 Bot 能力对标和 Hermes Agent 飞书实现阅读，进一步确认路线应按团队上下文场景拆解，而不是逐项问“企微有没有飞书同款接口”。飞书/Hermes 只作为产品和工程参考；企微文档评论/变更、智能表格变更、reaction、邮件、日历/任务/会议室等未被当前官方资料或后台确认的能力，不能写成已决事实。

决策

企业微信正式接入按场景分四层：

1. 人机实时交互：生产优先 Bot URL 回调；开发、smoke、回归和临时对话保留 Bot WS 长连接。该层覆盖私聊 Bot、群里 @Bot、被动回复、主动回复，以及已保存 chatid 的主动群消息。
2. 显式知识沉淀：作为当前 MVP 默认采集策略。团队成员需要入库就 @Bot、私聊 Bot、转发给 Bot，或写入指定文档/日报入口；普通聊天不作为默认被动采集对象。
3. 企业系统能力：用自建应用 API/回调、Token、EncodingAESKey、可信 IP、access_token、应用消息、通讯录 API 和企业级 API 建立通讯录、部门成员、权限、文档/日报、会议、应用消息和主动提醒能力。
4. 全量被动采集增强：会话内容存档降级为未来增强项。只有需要不 @ 也采集普通群聊/单聊、历史消息、合规归档、媒体下载或 seq/cursor checkpoint 时，才单独开通和验收。

智能机器人 URL 回调不能被描述为“企业系统集成入口”。它只解决智能机器人相关消息进入 Harness 的问题。

公网回调不能被描述为“全量聊天源”。它只解决企业微信把机器人消息、应用事件或应用相关消息推给 Harness 的问题。

会话内容存档不能被描述为当前 MVP 可用性的前置条件。它是全量被动采集、历史回溯和合规审计增强项。

飞书/Hermes 对标产生的实施原则同步进入本 ADR：

• 事件通知只作为触发和 Evidence 元数据，不直接自动做事；详情、附件、评论线程、会议纪要和写回动作必须再经对应 API 与 Tool Gateway。
• Bot 身份、自建应用身份和用户授权身份必须区分；需要用户身份或文档权限的数据，不能用 bot 或管理员身份绕过。
• 群入口默认要求显式 @Bot 或转发；群上下文默认按个人 session 与共享 Evidence 分离，共享 Knowledge 必须经 Knowledge Card review。
• 准入策略先于 Agent，包括 allowlist、群规则、require_mention、bot-sender admission、自回声过滤、去重、频控和审计。
• 所有事件、显式提交、主动询问回复和写回动作先进入 Evidence Registry / Connector Callback Ledger，再按权限投影给 Context Router。

理由

• 当前业务目标是先让团队成员能主动把有价值消息、日报、文档和会议线索沉淀到知识库，而不是一开始解决所有历史和普通聊天采集。
• Bot WS 已经证明机器人入口可用，但它只是智能机器人通道的长连接接入方式；生产入口在公网 HTTPS 可用后应优先验证 Bot URL 回调。
• 主动 @Bot、私聊 Bot、转发 Bot 和指定文档/日报入口能覆盖大部分“需要知识库沉淀”的主动场景，同时显著降低合规、权限、成本和上线复杂度。
• 自建应用回调/API 是企业微信企业集成的稳定入口，适合应用事件、主动消息、通讯录、文档/日报、会议和写回。
• 会话内容存档仍是“收集大家在企微上的所有普通消息、历史消息和媒体”这类需求的必要条件，但应作为单独增强项目评估开通、告知、密钥、SDK、媒体、checkpoint 和 restricted Evidence 边界。
• WireGuard 只能作为服务器国际出口方案，不能破坏企业微信公网 callback 的入站回包路径，也不能让企业微信 API/SDK 出口 IP 失控。
• Hermes 飞书实现已经证明复杂团队入口需要先有准入、事件去重、资源下载边界、文档评论授权、按人会话隔离和工具作用域限制；这些是企微实现质量要求，不代表对应企微事件已全部确认存在。

影响

• workspaces/variai/site/knowledge/wecom-official-full-route.md 成为团队阅读层的企微分层接入入口，首屏必须明确当前 MVP 不依赖会话内容存档。
• workspaces/variai/site/knowledge/wecom-feishu-bot-benchmark-roadmap.md 作为飞书能力对标后的企微团队上下文路线图，列出产品场景、待验能力和 Hermes 设计参考。
• workspaces/variai/knowledge/projects/企微全量接入开发计划.md 按人机实时交互、显式知识沉淀、企业系统能力和全量被动采集增强组织后续开发和验收。
• workspaces/variai/connectors/wecom/contracts/aibot-ws-channel.md 继续保留，但定位为智能机器人 Bot WS 开发/smoke/回归契约；后续应补 Bot URL 回调契约。
• workspaces/variai/connectors/wecom/contracts/self-built-app-callback.md 成为自建应用 callback/API 的企业集成契约。
• framework/connectors/wecom/callback.py 和 scripts/wecom_callback_conformance.py 是自建应用 callback/API 的 synthetic scaffold，不代表真实公网 handler 已上线。
• 后续真实凭证、Token、EncodingAESKey、RSA 私钥、用户 ID、群 ID、回调 payload 和消息正文不得进入 Git。

后续动作

• 完成公网服务器域名、HTTPS、443/NAT 或反代配置，确保智能机器人 URL 回调和自建应用 callback 都能打到这台 Ubuntu。
• 在智能机器人后台配置 URL 回调，验收成员私聊 Bot、群里 @Bot、被动回复、安全投影和已保存 chatid 的主动群消息边界；Bot WS 保留为开发/回归入口。
• 固化团队显式知识沉淀约定：需要入库就 @Bot、私聊 Bot、转发给 Bot，或写入指定文档/日报入口。
• 在企微后台配置自建应用回调 URL、Token、EncodingAESKey、可信 IP、通讯录/文档/应用消息/会议权限。
• 把当前 callback scaffold 接到真实 HTTP handler、access_token 缓存、应用消息发送、通讯录最小字段同步和主动提醒。
• 为 Bot URL 回调和自建应用事件补准入/去重/群规则/require_mention/bot-sender 策略，并把文档评论/变更、智能表格变更、reaction、文件、邮件、日历/任务/会议室列入待官方/后台验收清单。
• 只有当全量被动采集、历史回溯或合规审计成为明确需求时，再发起会话内容存档小范围试点，明确员工告知、试点范围、RSA 公钥、SDK 拉取、媒体下载和 seq/cursor checkpoint。

ADR-041：知识抽取采用 Claude-LLM 并以确定性治理为底座

日期：2026-06-17

状态：有效。修正前期“显式知识沉淀里的抽取一步靠规则启发式”的底层做法；不改变 ADR-040 的企微分层路线与准入治理底座。

背景

前期 schedule_todo_assistant 的工作项抽取（是否工作项、负责人、时间）靠规则启发式（关键词、infer_owner_ids、confidence_for）。团队明确：整套知识库都基于 Claude SDK 开发，这类语义判断应交给大模型而不是堆规则。但 LLM 会幻觉（实测 Haiku 把“发哥”错解析为无字面重叠的“张伟”），不能让它直接决定负责人身份这类强约束字段。

决策

知识抽取采用 “确定性护栏 + Claude 大脑” 架构：

1. 语义抽取交给 Claude-LLM：是否工作项、任务标题、时间、owner_mention 由 Claude 结构化输出。framework/llm/claude_client.py 提供可插拔鉴权 + 模型/effort 可配 + 结构化输出薄封装；framework/llm/work_item_extractor.py 为抽取组件，规则保留为 fallback。
2. 负责人身份解析是确定性代码，不是 LLM：LLM 只产出 owner_mention，由代码按群花名册字符重叠解析（去敬称 哥/姐/总/老；唯一命中→解析，0 或 ≥2→反问）。花名册可插拔：当前 synthetic，待真实通讯录接入后只换数据源、解析逻辑不变。
3. 确定性治理底座保留：准入/去重/频控、Connector Callback Ledger、Evidence Registry、Knowledge Card review、Tool Gateway 不变（沿用 ADR-040“准入策略先于 Agent”）。
4. 模型策略：开发期用 claude-haiku-4-5，模型/后端可配，遇到瓶颈再升级；生产改用专用 API key + raw SDK 跑 Sonnet/Opus。

理由

• 规则启发式覆盖不了真实表达的多样性，语义判断是 LLM 的强项；但负责人、权限这类强约束字段一旦幻觉代价高，必须由确定性代码兜底。
• 把“LLM 只产出 mention、代码做花名册解析 + ask-confirm 反问”拆开，既拿到 LLM 的泛化，又挡住幻觉。已在真实「变分小组」群里跑通“反问 → @ 澄清 → 补全登记待办”闭环（scripts/wecom_capture_llm_demo.py）。
• 订阅 OAuth token 外部只放行 Haiku，开发期用 Haiku + 工程化护栏即可；模型可配使“升级=改配置”。

影响

• 新增 framework/llm/claude_client.py、framework/llm/work_item_extractor.py；demo scripts/wecom_capture_llm_demo.py。
• 后续把 LLM extractor 正式接进 framework/workflows/wecom_message_pipeline.py 默认抽取步、规则保留 fallback，并补单测 / 脱敏 fixture。
• 真实通讯录接入后，花名册数据源从 synthetic 换为真实 WeCom 通讯录，解析与 ask-confirm 逻辑复用。
• 凭证只走环境变量 / 运行时读取，绝不进 Git；Claude OAuth token 运行时从 ~/.claude/.credentials.json 读取。

ADR-042：企微助手检索采用 Claude Code Sonnet 大脑、MCP 检索和确定性门禁

日期：2026-06-18

状态：有效；检索后端口径已由 ADR-044 订正为 ES-BM25 + IK + bge-m3 CPU hybrid。

决策

企微助手采用「护栏 + 大脑」分层：Claude Code Sonnet 经 claude -p 订阅路径负责多步检索、读原文、综合回答和提出结构化动作 proposal；确定性护栏负责人名、时间、权限、确认和外部动作执行。

知识检索走 MCP 工具：先搜候选，再读团队文档或章节原文，不能退化成单次 top-k RAG。MCP 不是安全边界，写动作仍由 Tool Gateway 和确定性门禁控制。

影响

• framework/mcp/knowledge_search_server.py 暴露团队知识检索工具。
• framework/llm/claude_code_client.py 承担 Sonnet 大脑封装。
• ADR-044 之后，ES 后端默认可用 hybrid 召回，embedding 不可用时回落 BM25。

ADR-043：企微动作智能体护栏分层与对话上下文

日期：2026-06-19

状态：有效。承接 ADR-040、ADR-041 和 ADR-042，把「护栏 + 大脑」原则推进到副作用动作。

决策

动作型智能体不能只靠模型生成参数。大脑只负责理解用户意图、提出动作和补问缺口；确定性代码负责 requester 身份、自指参数兜底、成员解析、时间解析、权限状态、确认态和执行结果登记。

企微 API 能力以 connector-status.json live 状态为准。已验证可用的能力才执行；遇到 OA 权限门 48002 api forbidden 的加日程、订会议室、发起审批等动作，bot 必须诚实降级，不能伪装成功。

影响

• 动作 proposal schema 只表达用户确实提到的人和对象；“请求人/我/本人”由护栏用真实 requester 兜底。
• 每个动作先静态审计，再在安全范围内 live smoke，最后同步更新 connector-status.json 和 project-status.json。

ADR-044：本机 CPU 落地 ES 语义召回 Hybrid 检索

日期：2026-06-19

状态：有效。订正 ADR-042 中“无 GPU 时 ES-BM25+IK 即本机终态、bge-m3/reranker 等 GPU 后再考虑”的口径。

背景

本机无 GPU，但有 16 核、约 24G 可用 RAM 和 ES 8.17。对标用户私有仓库 alpc91/AgenticSearch 后，确认 bge-m3 可以作为独立 CPU REST 服务运行，避免把 torch / sentence-transformers 放进主 .venv。

决策

• /home/crf/model-service 使用独立 uv venv，运行 BAAI/bge-m3 embedding 服务，绑定 127.0.0.1:8001。
• ES variai-knowledge mapping 新增 embedding dense_vector：1024 维、index=true、cosine。
• 索引端按章节调用 /embed_batch，每章节写一个向量。
• 查询端做 BM25 + dense_vector kNN 双路召回，并用应用层 RRF 融合；rerank 保留 HTTP 接口，默认关闭。
• embedding/kNN/rerank 任一失败时，知识检索回落 BM25。

验证

• /health 返回 bge-m3、device=cpu、dims=1024、load_seconds 约 4.5。
• /embed 单条 roundtrip 约 66ms；4 条 /embed_batch roundtrip 约 75ms。
• scripts/wecom_index_knowledge.py --require-embeddings --embedding-batch-size 8 重建 2093 个章节，全部写入 1024 维向量。
• 查询「订阅账号的大模型应该通过命令行大脑而不是原始 SDK」时，BM25 top5 未命中 ADR-042；hybrid 约 121ms 在 rank 3 召回 ADR-042 理由小节。

影响

主仓只保留 HTTP client 和可注入 fake 的 hybrid 逻辑；CI 不连真实 ES/模型。系统级 scripts/systemd/model-embedding.service 已提供，当前会话因 sudo 需要密码，已先启用 user systemd service。

ADR-045：站点迁自建应用工作台与权限投影铺垫

日期：2026-06-19

状态：提议 / draft。本 ADR 只给迁移设计、最小切片和实施计划；本轮不修改生产 Caddy、systemd、凭据或企业微信后台配置。

决策

MkDocs 仍作为团队阅读层生成器，但自建应用工作台的生产展示目标迁到 专用子域名 下的自托管 Caddy 路径。推荐入口为 https://专用子域名/workbench/，由企业微信自建应用后台“应用主页”指向该 URL；企业微信只负责入口和身份授权，不托管静态站点。

第一阶段部署的是同一份 MkDocs 静态 artifact：mkdocs build --strict 生成 site/，部署流程同步到 /srv/variai/workbench-site/releases/<timestamp>/，再原子切换 /srv/variai/workbench-site/current。Caddy 必须保持 /wecom/... 回调优先，再用 /workbench/ 承载静态站点，避免静态兜底吞掉回调验签。

本轮最小切片把 workspaces/variai/site/index.md 改成“项目 Artifact 看板”：首页首屏直给当前状态、今日进度、近期 ADR、风险和下一步；事实源仍是 registry/project-status.json 与 knowledge/decisions/ / knowledge/wiki/，生成页不是事实源。

上线步骤

1. Build：运行 mkdocs build --strict，或本地预览 bash scripts/serve_site_locally.sh。
2. Caddy：主智能体参考 scripts/workbench-caddy-template.caddy 加 /workbench/ 站点块，保持 /wecom/... 优先。
3. 企微后台：把自建应用“应用主页”URL 指向 https://专用子域名/workbench/。
4. 可选 OAuth：后续用网页授权 code 识别成员并映射到 registry member；未完成前只是成员公共静态站点，不代表权限投影已生效。

非目标

• 不上线 Caddy、不 reload 生产服务、不安装 systemd。
• 不配置企业微信后台、不读取或移动凭据。
• 不实现 OAuth gate、session、动态 workbench 或 permission view runtime。

ADR-046：自主知识沉淀与投影循环

日期：2026-06-19

状态：提议 / draft。承接 ADR-037 的 Evidence / Ontology / Runtime Projection 主抽象；本 ADR 定义产品上线后的后台知识沉淀循环，不代表实现已经完成。

决策

产品上线后采用“自主知识沉淀与投影循环”：后台 worker 按定时或事件阈值读取新增 Evidence window，经过确定性 intake / redaction / permission slicing，再由 Claude Code Sonnet 大脑生成结构化 Knowledge candidate，最后通过确定性 gate 自动投影低风险内容或进入 Semantic Review Queue。

流程是：

Evidence window
  -> deterministic intake / redact / permission slicing
  -> Sonnet distillation
  -> Knowledge candidate normalization
  -> deterministic gate
  -> scoped projection OR Semantic Review handoff

候选必须携带 source evidence refs、source hashes、claims、permission scope、risk flags、projection plan、review_required 和 idempotency key。没有逐条来源的模型断言不能进入稳定 Knowledge。

护栏

自动投影仅限低风险、追加式、可撤回的候选，例如已脱敏活动摘要、无冲突项目进展补充或已 review 结论的重投影。涉及真实个人身份、客户、合同、财务、HR、合规、权限扩大、删除/合并/supersede、稳定 ADR/wiki 冲突、低置信或来源不稳定的内容，必须进入 Semantic Review Queue。

本方案不是恢复已删除的 daily-maintenance 自动 PR 循环：没有新增 Evidence、权限变化或 review 结论变化时必须 no-op，不得为了刷新生成页、证明系统还活着或制造 PR 而运行。

影响

Evidence Registry、Knowledge Card、ContextDocumentRecord、SearchConnector、Semantic Review Queue 和 Claude Code Sonnet 大脑被串成同一产品闭环。站点、企微文档和检索索引仍从结构化源生成；生成物不是事实源，公开 Site 不展示 restricted Evidence 或未审敏感候选。

ADR-047：上下文充分性闸门与主动闭合缺口

日期：2026-06-19

状态：提议 / draft。承接 ADR-037 主抽象与 ADR-046 自主沉淀循环；门控 ADR-046 的上线启用。

背景：一个 code-confirmed 的偏离

北极星之一是“让智能体主动补充上下文”。但当前实现存在不对称：动作轴主动补全（时间/人名/缺参数解析不出就向上追问），知识轴却被动封口——查询查不到只回“暂时没找到、我会继续补”而无任何东西真去补；自主循环有事件就产候选、无充分性闸门；摄取不澄清就沉淀。诚实标注缺口（防幻觉）到处都有，主动闭合缺口（防坑）在知识轴上完全缺失。开发 agent 自身也犯过同构错误（外部文章 WebFetch 被反爬即封口，而非换路子搜/问）。产品上线后会复现：用户给薄而含糊的输入，bot 不在源头澄清，知识库逐渐堆满低可追溯半成品。

决策

知识轴补上动作轴早有的能力：充分性闸门 + 主动闭合。作答/摄取/自主沉淀前评估上下文是否足以成为可追溯、无歧义的知识；不足则主动闭合（换稳定源搜、交叉引用已有知识、对方在场时问一个具体低摩擦问题），都闭不上则登记成一等公民的“信息债 / open-question”待补项，绝不把半成品当稳定知识沉淀。能力沉淀为技能 proactive-context-completion，软链进 .claude/skills/ 与 .codex/skills/，使产品 bot/循环与开发 agent（Claude Code / Codex）共用同一份——产品能力提升即开发 agent 能力提升。

护栏

闸门只在确有不足时触发一个好问题，不对每条消息盘问一长串，避免退化成机械客服。不实现字面的 AGFS 虚拟文件系统，只取“上下文即可主动管理的活基质 + 主动闭合缺口”的原则。ADR-046 自主循环在本闸门接入前不启用，否则会主动制造半成品 draft。

影响

新增技能与 [[kb-faithfulness]] 互补（忠实=别编没有的；主动补全=主动去拿没有的，闭不上才显式待补）。待实现：闸门接入 bot 作答路径与自主循环、信息债 backlog 作为 registry 一等对象并被主动重捞。外部参考印证见 knowledge/wiki 的 Claude Code Artifacts + Lightspeed File Systems for Agents 提炼页。