Framework 与 Workspace 边界¶

核心结论¶

Harness repo 同时承载两类资产：

Framework：可打包、可复用、可交付给其他团队的通用能力。
Workspace：某个团队、部门、项目组或事项的私域工作区。

当前 workspaces/variai/ 是第一个 dogfood workspace。它用于验证 Framework 是否能支撑真实研发、知识沉淀、实验和发布，但它的私域知识不进入通用产品包。

为什么现在要定边界¶

当前阶段还没大规模接入企微和真实协作者，重构成本最低。如果现在不把边界定清楚，后续会出现三个问题：

通用代码、模板、实验工具和当前项目知识混在一起，难以产品化。
交付给其他部门或公司时，容易带出 OrgReOrg 私域知识、真实讨论和配置。
新团队不知道资料、知识、状态、实验、发布页面和连接器应该放在哪里。

因此本轮重构把旧的 domain / vault / docs 口径升级为 workspace 下的六个区：

workspaces/<workspace-id>/
  evidence/      原始证据和来源线索
  knowledge/     review 后的人类可读知识
  registry/      机器可读本体、状态、权限、路由和 review 队列
  site/          发布给团队阅读的网站源码
  connectors/    当前工作区的外部系统接入边界
  outputs/       实验、demo、loop 和生成器输出

Framework 放什么¶

framework/ 只放可以被别的 workspace 复用的能力：

区域	内容
`framework/context/`	Context Router、SearchConnector、ContextDocument、运行时投影契约
`framework/workflows/`	ask、knowledge card、review、promote、reindex 等通用 workflow
`framework/connectors/`	可复用 connector adapter 和 org directory 契约
`framework/evals/`	benchmark、conformance、report generator
`framework/governance/`	package boundary、workspace blueprint、secret lint、review/publish 检查
`framework/templates/`	新 workspace 的 site、knowledge、ADR、skill 等模板
`framework/task_skills/`	可执行知识对象、manifest、模板和 lint

Framework 不应依赖当前 orgreorg-demo 私域数据。需要示例时，只能使用 synthetic 或脱敏 fixture。

Workspace 放什么¶

workspaces/variai/ 是当前项目私域工作区：

区域	内容	是否进入通用产品包
`evidence/`	讨论、链接、原始资料、上传文件、证据 registry	只复制结构，不复制当前内容
`knowledge/`	wiki、项目计划、ADR、系统模板和维护日志	只复制模板，不复制当前知识
`registry/`	`workspace-topology.json`、project status、experiment registry、权限和 review 队列	当前数据排除，新 workspace 重新生成
`site/`	MkDocs 发布站点源码	复制页面结构和模板，不复制当前私域内容
`connectors/`	企微等接入说明、contracts、synthetic fixtures	可拆分；真实配置不提交
`outputs/`	实验报告、demo 输出、生成结果	默认 regenerated / excluded

依赖方向¶

依赖方向必须单向：

framework/*  -> 通用 framework 模块
scripts/*    -> 薄 wrapper，调用 framework
tests/*      -> synthetic / sanitized fixture
workspace/*  -> 当前工作区的 Evidence / Knowledge / Registry / Site / Outputs

不允许通用 Framework 反向依赖当前 demo workflow 或当前 workspace 私域路径。scripts/package_boundary_lint.py 会检查 framework/**/*.py 不能导入 framework.workflows.orgreorg_demo。

当前落地¶

WorkspacePaths 已把 site/evidence/knowledge/registry/connectors/outputs 作为正式路径契约。
workspace.blueprint.json 定义新 workspace 初始化时哪些复制、哪些模板化、哪些清空、哪些排除。
packaging.manifest.json 把 workspace_private、mixed、generated 和 packageable 边界机器化。
workspaces/variai/registry/workspace-topology.json 是当前工作区轻量本体和私域拓扑入口。
workspaces/variai/registry/workspace-inventory.json 记录当前 workspace 私域资产。
framework/templates/site/ 提供新 workspace 的发布站点模板。

验证命令¶

python scripts/workspace_blueprint_lint.py --dry-run
python scripts/package_boundary_lint.py
python scripts/workspace_topology_lint.py
uv run mkdocs build --strict

维护规则¶

新通用能力优先放 framework/。
新私域事实先进入 workspaces/<workspace-id>/evidence/ 或 knowledge/。
机器可读状态进入 registry/，生成页面从 registry 或 eval 输出再生成。
发布站点只承载稳定、可读、可审查内容。
每日维护可以刷新生成物并开 PR，但不能绕过 review 静默改写私域知识。