跳转至

框架与领域知识解耦

核心结论

当前 repo 同时承担两类职责：

  • 产品框架 Demo：未来可以抽成通用产品、模板、工具链和开源底座。
  • 当前项目领域知识：围绕“如何开发 OrgReOrg / Harness 这个 Demo”沉淀的私域知识。

这两类内容现在可以放在同一个 repo 中试用和验证，但从第一天就要标清边界。未来打包成通用产品时，只带走框架层、工具层、模板层和通用流程，不带走当前团队的私域知识、真实组织数据、真实讨论记录和客户/项目材料。

为什么现在要定边界

当前 repo 是产品 MVP。它要验证的不只是某个搜索或企微接口，而是一个团队如何围绕 repo 运转：

text 讨论 -> 捕获 -> 编译 -> 开发 -> 测试 -> 发布 -> 复盘

如果边界不清，后续会出现三个问题：

  • 通用代码、模板和私域知识混在一起，无法产品化。
  • 未来开源或交付给其他部门时，容易带出内部知识和真实数据。
  • 每个部门拿到模板后，不知道哪些应该替换成自己的领域知识，哪些应该保留为平台能力。

因此，当前 MVP 必须同时验证功能和可剥离性。

两层资产

可打包层

可打包层是未来产品、模板或开源底座应该保留的部分。

类型 当前表现 未来形态
Agent 工作规则 AGENTS.md、CLAUDE.md 项目空间初始化模板
文档发布链路 mkdocs.yml、docs/ 站点结构、Cloudflare 发布规则 文档站模板和发布模块
知识库结构 vault/00-inbox 到 vault/90-system 的分层 团队 vault 模板和 lint 规则
状态看板 framework/dashboard/project_status.py、scripts/generate_project_progress.py、docs/project-progress.md 结构化 dashboard generator
任务技能包规范 本体层中的可执行知识对象、验证方法、模板 可安装/可导出的任务包
实验与评测框架 framework/evals/、scripts/ wrapper、tests/、benchmark fixture 规范 eval harness 和报告生成器
Connector contract SearchConnector、Tool Gateway、WeCom adapter contract 通用 connector SDK
权限和审计规则 权限字段、review 状态、审计设计 Policy plane / audit module

这些内容应尽量避免写入当前团队特定事实。需要示例时使用 synthetic_internal_demo 或匿名化样例。

私域领域知识层

私域领域知识层属于当前团队、当前项目或未来某个部门自己的知识资产，不进入通用产品包。

类型 当前例子 处理方式
项目决策 当前 OrgReOrg 的 ADR、路线图、实验结论 留在当前 repo，作为 Demo 领域知识
真实讨论 用户口述、群聊、会议纪要、观点碰撞 进入 vault，经 review 后选择性发布
组织结构 真实 owner、部门、职责、通讯录 默认私有；公开包只放合成样例
业务材料 客户、合同、财务、CRM、项目状态 只通过权限化 connector 访问，不进入模板
团队知识库 当前团队如何开发这个 Demo 的知识 可作为案例，不作为通用默认知识
发布网站内容 对团队有用的研发进度和方案文档 当前站点保留；产品包只保留页面模板

当前 MVP 的领域知识就是“如何开发、验证和迭代 OrgReOrg / Harness”。未来某个部门部署后，它的领域知识会替换成“这个部门正在做什么、负责人是谁、流程和业务事实是什么”。

Domain 不是单一数据桶

补充一个更精确的边界：domain/ 下面不是只放某个项目的一坨资料，而是要表达一个组织内部的私域拓扑。

未来 Framework 交付给一个公司后，这个公司会有：

  • 组织级目录和公共事实。
  • 部门级事项，例如财务、People Ops、研发、销售。
  • 员工个人事项，例如入职、报销、绩效、审批。
  • 项目或课题组事项，例如当前 OrgReOrg Framework MVP。
  • 跨部门项目和临时任务。

因此每个 domain/<domain-id>/ 至少要能表达：

text organization/ departments/ people/ projects/ tasks/ context-libraries/ routing/ permission-views/ domain-topology.json

framework/ 提供通用机制；domain/<domain-id>/ 提供具体组织的部门、人员、项目、任务、上下文库、路由规则和权限视图。路由和权限管理后续都要基于这套 topology，而不是只基于文件路径或单一 RAG 库。

当前已落地结构

为了避免后续代码量变大后再重构，repo 已经前置建立基础边界：

text harness/ framework/ # 可打包：通用框架代码、接口、模板、评测和治理检查 connectors/ # connector contract 和 adapter 边界 context/ # evidence / ontology projection / context document / search contract dashboard/ # project_status / experiment_report / 看板生成器 evals/ # 可复用评测 harness 和报告生成器 governance/ # 打包边界、policy、audit、安全检查 policy/ # 权限、review 状态、审批和输出净化 templates/ # 项目空间、vault、docs、ADR、knowledge card 模板 task_skills/ # 可执行知识对象、manifest、模板和 lint workflows/ # capture / search / ask / review / publish 等 loop domain/ orgreorg-demo/ # 当前 Demo 的组织私域拓扑和领域知识索引，不进入通用产品包 domain-topology.json # 私域拓扑：组织、部门、人员、项目、任务、上下文库、路由、权限视图 wecom/ # 混合区：adapter 可打包，真实组织数据不可提交 workspace.blueprint.json # 可打包：新团队/项目工作空间的结构契约 packaging.manifest.json # 机器可校验的打包边界清单

当前 docs/ 和 vault/ 暂时不大搬迁，因为它们已经被 MkDocs、知识沉淀流程和现有链接引用。实现代码已先迁入 framework/，后续原则是：

  • 新增可复用代码优先进入 framework/。
  • 第一批通用引擎已经迁入 framework/evals/、framework/context/、framework/workflows/ 和 framework/governance/，scripts/ 保留 CLI wrapper。
  • docs/ 和 vault/ 保持当前项目知识生产和发布功能；通用页面模板后续迁入 framework/templates/。
  • domain/orgreorg-demo/domain-inventory.json 记录当前 Demo 的领域资产，未来交付给其他团队时替换。
  • domain/orgreorg-demo/domain-topology.json 记录当前 Demo 的组织私域拓扑，至少覆盖个人、部门、项目三类 demo。
  • domain/orgreorg-demo/project-status.json 是当前 Demo 的结构化项目状态数据；framework/dashboard/project_status.py 和 scripts/generate_project_progress.py 负责生成 docs/project-progress.md。
  • workspace.blueprint.json 记录未来初始化新团队 repo 时各层该复制、模板化、清空还是排除。
  • framework/workspace.py 提供 WorkspacePaths，让 framework 实现通过显式 workspace/root 参数访问 docs/、vault/ 和 domain/<id>/，避免把当前 orgreorg-demo 路径固化进可打包逻辑。
  • framework/context/local_search.py 抽出本地 Markdown/token 检索基础能力；framework/connectors/org_directory.py 抽出组织目录读取能力，避免其他 framework 模块反向依赖 orgreorg_demo。
  • package_boundary_lint 已增加 Python import 边界检查：除 demo workflow 自身外，framework/**/*.py 不应导入 framework.workflows.orgreorg_demo；共享能力必须先下沉到 framework/context、framework/connectors、framework/templates 或其他通用模块。

边界校验命令：

bash python scripts/workspace_blueprint_lint.py python scripts/package_boundary_lint.py

代码依赖边界

目录拆分只是第一层。更关键的是依赖方向：

```text framework/context、framework/connectors、framework/evals、framework/governance -> 可以依赖通用 framework 模块 -> 不应依赖当前 demo workflow 或 domain 私域数据

framework/workflows/orgreorg_demo.py -> 可以组合通用模块形成当前 repo 的本地 MVP ```

这条规则的原因很直接：orgreorg_demo 是当前项目的 dogfood workflow，不是未来产品包的基础库。其他可打包模块如果从它导入 ROOT、tokenize、search 或组织目录读取函数，短期能省代码，长期会把当前 demo 的私域路径和流程假设带进通用产品。

当前已经完成的拆分：

  • tokenize、SearchChunk、SearchResult、split_markdown、search 下沉到 framework/context/local_search.py。
  • load_directory 下沉到 framework/connectors/org_directory.py。
  • orgreorg_demo.py 保留兼容导入面，脚本和旧测试仍可使用原函数名。
  • scripts/package_boundary_lint.py 会阻止 framework 层重新反向导入 demo workflow。

历史目录归属

text harness/ AGENTS.md # 可打包：Agent 工作规则模板，但当前内容含本项目协作规则 CLAUDE.md # 可打包：Claude Code 协作规则模板 mkdocs.yml # 可打包：站点模板；nav 中的领域页需替换 domain/orgreorg-demo/ project-status.json # 私域：当前 Demo 的项目状态数据 docs/ project-progress.md # 混合：由结构化状态生成；内容为当前项目领域知识 knowledge/ # 混合区：架构/框架页可打包，当前项目 ADR/实验为私域案例 collaboration/ # 混合区：协作流程可打包，仓库远程和团队约定为私域配置 vault/ 00-inbox/ # 私域：原始讨论和临时输入 10-raw/ # 私域：原始资料 20-wiki/ # 私域为主，可抽象出模板和 schema 40-decisions/ # 私域为主，通用 ADR 模板可打包 90-system/ # 混合区：模板/lint 可打包，索引和日志为私域 scripts/ *_demo.py # 可打包候选：若不依赖当前领域数据 *_benchmark.py # 可打包候选：若 fixture 可匿名化 tests/ test_*.py # 可打包候选：验证框架和合成样例 wecom/ # 混合区：adapter 可打包，真实组织数据不可提交

早期设想中的 framework/ / domain/ 拆分已经开始落地；剩余迁移会随着真实代码稳定后分批执行，而不是一次性搬动所有现有文档。

新增或迁移文件时，先更新 packaging.manifest.json，再更新测试和文档。

企业微信目录边界

未来 wecom/ 是企业微信接口开发区，但它也要分层：

  • 可打包：WeCom adapter contract、消息 schema、回调验证逻辑、重试/限流策略、合成测试 fixture。
  • 私域：真实 corp_id、应用密钥、回调 token、联系人、群聊、消息正文、客户或项目材料。

企业微信接入后，真实消息先进入 inbox/raw 或结构化事件表，再通过 review 形成 knowledge card。不要把真实聊天记录直接写进可打包的测试 fixture。

打包检查清单

未来从当前 repo 抽通用产品包时，至少要跑一遍检查：

  • docs/ 中是否包含当前团队特定的业务事实。
  • vault/ 是否被排除，或只保留空模板和合成样例。
  • wecom/ 是否只包含 adapter、schema、合成 fixture 和安全说明。
  • scripts/ / tests/ 是否只依赖匿名化 fixture。
  • mkdocs.yml 导航是否替换为通用模板导航。
  • AGENTS.md 是否去掉当前团队远程仓库、分支、Cloudflare 等私有配置。
  • 是否存在 secret、token、真实用户、真实客户、真实合同或内部链接。
  • 是否有 license、README、安装脚本和最小 smoke test。

对后续开发的影响

  • 新增代码时，先判断属于 framework、connector adapter、demo domain 还是 private data。
  • 新增可打包代码时，默认放入 framework/，不要继续堆在 scripts/。
  • 新增 CLI 时，优先做成 scripts/ wrapper 调用 framework/ 模块。
  • 新增任务技能包时，放入 framework/task_skills/packages/，并运行 python scripts/task_skill_package_lint.py。
  • 新增 fixture 时，默认使用合成数据，并显式标注 synthetic_internal_demo。
  • 新增文档时，区分“通用方法论”和“当前项目案例”。
  • 新增 WeCom 能力时，adapter contract 和消息 schema 可打包，真实组织通讯录和消息内容不可打包。
  • 做 dashboard generator 时，生成器和校验逻辑可打包，当前项目状态数据不可打包。
  • 做上下文库和主动询问时，先看 domain-topology.json：用户是谁、属于哪个部门、任务属于个人/部门/项目哪一类、允许调用哪些上下文库。
  • 任何目录边界变化都要跑 python scripts/package_boundary_lint.py。
  • domain 拓扑变化要跑 python scripts/domain_topology_lint.py 和 python scripts/domain_scope_eval.py --check-report。

相关决策