Agentic Knowledge Workspace Blueprint

这页解决什么问题

当前 repo 不只是一个研发仓库，也是未来产品形态的最小样板：一个团队、项目组或部门可以拥有类似的工作空间，用来承载知识库、状态看板、实验、决策、任务技能包、Connector 和发布站点。

如果这些资产没有提前分层，后续产品化时会遇到两个问题：

• 通用工具底座、当前项目知识和真实组织数据混在一起，无法打包给其他团队。
• Agent 和协作者不知道新文件应该放在哪里，越开发越难拆。

因此新增 workspace.blueprint.json，把“一个可复用团队工作空间应该长什么样”变成机器可校验的结构契约。

当前分层

层	边界	当前路径	新团队初始化时怎么处理
Framework foundation	packageable	framework/, pyproject.toml, uv.lock	原样带走，作为通用产品底座
Workspace operations	mixed	AGENTS.md, CLAUDE.md, README.md, mkdocs.yml, .github/, scripts/, tests/	作为模板带走，再替换 repo、分支、发布、团队规则
Knowledge publishing	mixed	docs/, vault/90-system/templates/	站点和模板结构可复用，当前内容替换
Domain knowledge	domain_private	domain/orgreorg-demo/, vault/00-inbox/, vault/10-raw/, vault/20-wiki/, vault/30-projects/, vault/40-decisions/, vault/50-outputs/	不进入通用包，新团队用自己的领域知识重建
Connector surface	mixed	framework/connectors/, wecom/	contract 和合成 fixture 可打包，真实企微配置、联系人、消息必须排除
Generated artifacts	generated	site/	构建输出，不作为源码打包

为什么不是立刻大搬迁

docs/、vault/、scripts/ 和 tests/ 已经被 MkDocs、Obsidian、CI、本地 Demo 和网站链接引用。现在直接移动它们，会产生大量断链和低价值 diff。

更稳的重构方式是：

1. 用 workspace.blueprint.json 固定产品化边界。
2. 新增可复用实现默认进入 framework/。
3. scripts/ 保持 CLI wrapper，真实实现逐步迁到 framework/。
4. domain/orgreorg-demo/ 只记录当前 Demo 的结构化领域状态和资产索引。
5. docs/ 和 vault/ 暂时继续承担当前项目的知识生产和发布，但在蓝图中标明未来如何替换。

机器校验

新增命令：

bash python scripts/workspace_blueprint_lint.py python scripts/workspace_blueprint_lint.py --dry-run python scripts/workspace_blueprint_lint.py --scaffold-output /tmp/sample-workspace python scripts/domain_topology_lint.py python scripts/domain_scope_eval.py --check-report

基础 lint 会检查：

• layer id 是否唯一。
• boundary 和 package_action 是否使用合法枚举。
• 目录路径是否安全、是否存在。
• blueprint 中声明的目录是否被 packaging.manifest.json 覆盖。
• 初始化契约中的路径列表是否结构正确。

dry-run 会模拟一个新团队 workspace 的初始化/打包计划：

• copy_as_is：确认源路径存在，并且被 packaging.manifest.json 覆盖。
• template_then_replace：确认模板源路径存在，并且被 manifest 覆盖。
• create_empty：用 --team-id 替换 domain/<team-or-project-id>/ 这类占位路径，检查目标路径安全和冲突。
• exclude_from_package：区分真实路径和排除标记，检查 copy/template/create 不会把排除路径带进新 workspace。

当前 dry-run 结果：

text copy_as_is=5 template_then_replace=7 create_empty=14 exclude_from_package=6 dry run passed

scaffold 生成器会在指定目录生成一个最小可用的新团队 workspace：

• copy_as_is 真实复制可打包底座，例如 framework/、pyproject.toml、uv.lock、蓝图和 manifest。
• template_then_replace 不复制当前 OrgReOrg 的领域内容，而是生成可替换的 starter 文件：AGENTS.md、CLAUDE.md、README.md、mkdocs.yml、.github/、docs/ 和 vault 模板。
• create_empty 创建空目录并写入 .gitkeep，让新 repo 能保留 vault 和 domain 结构。
• scaffold seed 会额外生成最小 domain/<team-id>/domain-topology.json、project-status.json、experiment-reports.json、Semantic Review Queue、LoopRun seed 和 vault/50-outputs bootstrap 报告。
• exclude_from_package 不生成任何内容，只保留在 dry-run/scaffold 报告里用于审计。

当前 scaffold 快照检查确认：

• 新 workspace 会生成 domain/sample-team/organization/、departments/、people/、projects/、tasks/、context-libraries/、routing/、permission-views/，不会带入 domain/orgreorg-demo/。
• 新 workspace 会生成 docs/index.md、docs/project-progress.md、docs/knowledge/index.md、docs/knowledge/decision-log.md、docs/knowledge/experiment-reports.md 和 docs/_TEMPLATE_REPLACE.md，不会复制当前发布站点内容。
• 新 workspace 的 seed topology 可通过 validate_domain_topology()；seed experiment registry 可通过 validate_experiment_registry()；seed project status 可由 render_project_status() 渲染。
• 新 workspace 不生成 site/。
• framework/ 复制时会忽略 __pycache__、*.pyc 和 .DS_Store。

python scripts/package_boundary_lint.py 也会调用同一套蓝图校验，避免只跑旧命令时漏检。

框架层路径参数化

framework/ 不能把当前 demo 的私域路径当成产品默认行为写死。当前新增 framework/workspace.py，用 WorkspacePaths 统一派生这些路径：

• docs/
• vault/00-inbox/
• vault/10-raw/
• vault/20-wiki/
• vault/30-projects/
• vault/40-decisions/
• vault/50-outputs/
• vault/90-system/
• domain/<domain_id>/
• domain/<domain_id>/domain-topology.json

现有 CLI wrapper 仍默认使用当前 repo 的 orgreorg-demo workspace；但框架函数可以传入 WorkspacePaths.from_root(..., domain_id=...)，让未来新团队 repo 替换自己的领域数据，而不需要改框架实现。

对后续开发的约束

• Agentic Search、SearchConnector、评测、dashboard、任务技能包、治理检查等通用能力进入 framework/。
• 当前 OrgReOrg 的路线、实验结论、讨论、ADR 和项目状态仍进入 docs/、vault/、domain/orgreorg-demo/。
• 企业微信 adapter 的通用 contract 可以进入 framework/connectors/ 或 wecom/，真实组织数据不能提交。
• 每次新增顶层目录、改变打包边界或新增工作空间层，都要更新 workspace.blueprint.json 和 packaging.manifest.json。
• 每次新增 framework 模块，如果需要读写 repo 路径，应优先接受 WorkspacePaths 或显式路径参数。
• 生成网站、实验输出、缓存和真实业务材料不能混入可打包底座。

和未来产品的关系

未来把当前 MVP 打包成通用产品时，最小步骤是：

1. 原样保留 framework/、蓝图、打包清单和合成测试。
2. 把 AGENTS.md、CLAUDE.md、README.md、mkdocs.yml、.github/ 做成初始化模板。
3. 运行 workspace_blueprint_lint.py --scaffold-output <dir> --team-id <id> 生成 starter workspace。
4. 替换 domain/<team-id>/ seed，把组织、部门、人员、项目、任务、上下文库、路由和权限视图改成真实团队数据。
5. 只保留 vault 目录结构和模板，不带当前项目知识。
6. 替换 docs 导航和示例页面。
7. 检查所有 Connector 只包含 contract、schema、合成 fixture 和安全说明。
8. 跑 workspace_blueprint_lint、package_boundary_lint、secret scan、单测和 MkDocs strict build。

这让当前 repo 能继续作为“研用测一体”的真实试验场，同时不牺牲未来产品化和对外交付的可剥离性。