Domain Topology：组织私域拓扑契约¶
核心结论¶
domain/ 不是一个单一的 demo 数据桶。未来 Framework 交付给一个公司后，这个公司下面会有部门、课题组、项目、员工和具体任务。每一类对象都可能形成自己的私域知识和上下文库。
因此当前 MVP 从一开始就把 domain/<domain-id>/ 建成组织私域拓扑：
text
domain/<domain-id>/
organization/
departments/
people/
projects/
tasks/
context-libraries/
routing/
permission-views/
domain-topology.json
当前样例在 domain/orgreorg-demo/domain-topology.json。它不是产品默认数据，而是 dogfood 域：用来验证同一套 Framework 能否同时服务个人、部门和项目三类私域。
这份拓扑的产品意义是上下文管理：系统要根据当前员工、当前部门事项或当前项目任务，找到足够完成任务的最小上下文集合，并且只披露权限允许的部分。
在新的架构表述中，Domain Topology 是当前 P0 的轻量本体入口。它不是完整知识图谱，但必须承载本体层的最小语义：组织对象、上下文库、权限视图、可执行动作、writeback、知识制品和 Skill 的关系。原始资料仍保存在 Evidence；Topology 负责声明这些资料如何被解释、路由、授权和写回。
为什么要现在做¶
如果只按“当前项目知识”组织 domain/，后续会遇到三个问题：
- 个人入职、报销、绩效这类任务和项目研发知识混在一起，权限边界不清。
- 部门事项和跨部门项目无法判断应该查哪个上下文库。
- Framework 产品化时不知道哪些目录是通用底座，哪些是某个组织自己的私域资产。
所以现在先把拓扑契约定下来，再逐步接真实数据源。
契约字段¶
domain-topology.json 当前要求声明：
| 字段 | 作用 |
|---|---|
organization |
组织级身份和 root scope |
scope_taxonomy |
允许的私域类型：organization、department、personal、project |
departments |
部门、负责人、权限 scope 和路径 |
people |
员工、所属部门、角色和个人 scope |
projects |
项目、所属部门、owner 和项目 scope |
tasks |
具体事项，绑定个人/部门/项目与上下文库 |
context_libraries |
可路由的上下文库，含 scope_owner、permission_scopes、source_paths、projection_role、runtime_paths、index_strategy |
ontology_contract |
最小组织本体 contract：architecture layer、layer relationship、object、relationship、metadata、artifact、skill、provenance、rule、action、writeback event type |
ask_router_bindings |
主动询问绑定：scope、ask action、对象状态、throttle 对象，以及 task/context-library 匹配规则 |
routing_rules |
每个 demo/task 的候选上下文库、最大调用数和所需 permission view |
permission_views |
某个用户视角下可见的上下文库和 allowed_scopes |
demo_cases |
架构验收用例：个人、部门、项目三类都必须覆盖 |
isolation_requirements |
不同私域之间不能互相泄漏的规则 |
机器校验：
bash
python scripts/domain_topology_lint.py
校验会检查 ID、路径、部门/人员/项目引用、上下文库引用、permission view 引用、ontology contract 引用、重复 JSON key、上下文库运行时披露路径，以及是否同时覆盖 personal、department、project 三类 demo。
三段结构在 Topology 里的表示¶
本轮重构后，domain-topology.json 不再只是一张“上下文库路由表”。它必须显式声明三段主抽象：
| 架构层 | 在 Topology 中的字段 | 作用 |
|---|---|---|
| Evidence | ontology_contract.architecture_layers[id=evidence] |
原始资料、外部来源、代码包、会议、企微记录和业务系统对象的保真与追溯边界 |
| Ontology | ontology_contract.architecture_layers[id=ontology] |
对象、关系、元数据、规则、制品、Skill、Action、Writeback 和权限视图的统一语义模型 |
| Runtime Projection | ontology_contract.architecture_layers[id=runtime_projection] |
根据用户、任务、权限和当前目标投影最小充分上下文包的运行时机制 |
三段之间的转换关系进入 ontology_contract.layer_relationships：
| 关系 | 含义 | 必需元数据 |
|---|---|---|
evidence-to-ontology |
原始证据被清洗、review、沉淀成可维护本体制品 | source-uri、permission-scope、review-status |
ontology-to-runtime-projection |
本体规则、制品、Skill 和 Action 约束运行时披露与工具调用 | source-uri、permission-scope、review-status |
runtime-projection-to-evidence-readback |
运行时检索、Connector 和主动询问需要能回查原始 Evidence | source-uri、permission-scope、provenance-hash |
context_libraries 是 Runtime Projection 的入口对象，因此每个库还必须声明：
projection_role：当前是 search projection、source connector 还是 owner directory。runtime_paths：该库会被 D0-D5 渐进披露路径中的哪些步骤调用。index_strategy：具体索引或适配策略；命名不能再使用旧的 L3/L4 作为主模型。
Owner Registry Fallback¶
主动询问需要知道“应该问谁”。在企业微信通讯录 adapter 尚未接入前，当前 Framework 使用两层 owner registry：
- 优先读取显式组织目录：
vault/90-system/org-directory.json。 - 如果显式目录不存在，则从
domain-topology.json的people、departments、tasks和context_libraries派生本地 owner profiles。
对应实现是 framework/connectors/org_directory.py 的 load_owner_registry() 与 owner_profiles_from_topology()。这让本地 Demo 不依赖企微，也能让 route_ask_request_guarded() 在省略 people 参数时从 topology 生成候选 owner。
这个 fallback 不是最终通讯录实现。真实部署时，企微 adapter 应作为显式 owner registry 的来源，继续输出同一类 owner profile；Ask Router 只消费 registry，不直接绑定企微 SDK。
当前三类 Demo¶
| 类型 | Demo | 预期上下文库 | 禁止泄漏 |
|---|---|---|---|
| 个人域 | 员工入职与首次报销材料缺口 | personal_employee_ops、org_directory |
财务部门库、OrgReOrg 项目库 |
| 部门域 | 财务部门报销政策更新 | department_finance_ops、org_directory |
员工个人库、OrgReOrg 项目库 |
| 项目域 | 当前 OrgReOrg Framework MVP 开发 | project_orgreorg_knowledge、org_directory |
员工个人库、财务部门库 |
这三类不是最终业务功能，而是架构验收 fixture。它们回答的问题是：同一套 Framework 能不能服务公司内不同粒度的协同工作，并且不会互相污染。
最小充分上下文¶
每个任务最终都要生成一个上下文组合：
text
需求 -> 任务类型 -> 用户/部门/项目关系 -> permission view
-> route_domain_context feature-based 候选评分和过滤 -> 最终上下文集合
目标不是让 Agent 看到最多材料，而是在以下约束下选最小集合：
- 足够回答或推进当前任务。
- 不包含无关部门、项目或个人材料。
- 不超过用户和任务当前权限。
- 缺口不足时能生成 knowledge gap，并主动询问正确的人或系统。
这个 trade off 决定了后续 Agentic Search、主动询问、Tool Gateway 和权限视图的设计。
和 Framework 的关系¶
Framework 层提供通用能力：
- topology lint
- workspace scaffold
- SearchConnector
- Tool Gateway
- Context Router：当前本地 MVP 入口是
framework/context/domain_router.py的route_domain_context，评分器为domain_router_feature_v1 - Ask Router
- eval harness
- dashboard generator
Domain 层提供组织自己的事实：
- 谁属于哪个部门。
- 谁负责哪个项目。
- 某个任务要用哪些上下文库。
- 某个用户视角能看哪些 scope。
- 某个上下文库的数据源和生命周期规则。
未来打包产品时，Framework 保留；domain/orgreorg-demo/ 替换成客户组织自己的 domain。
最小 ontology contract¶
外部 Palantir 本体论材料提醒我们：domain-topology.json 不能只停留在“哪些上下文库能被路由”。本轮已经加入最小组织本体 contract，用来表达 Agent 面对的是哪些业务对象、哪些规则、哪些动作和哪些写回边界。
进一步校准后，本体层不应被理解为一组并列分层中的“某一层”。它是统一语义模型，至少包含：
```text Object 组织内可被识别和操作的业务对象
Relationship 对象之间的归属、负责、依赖、审批和证据关系
Metadata 来源、作者、时间、权限、版本、hash、review 状态和生命周期
Rule 什么时候允许查询、询问、执行、拒绝、脱敏、升级或重建索引
Artifact Markdown、ADR、实验报告、项目页、知识卡片和发布文档
Skill 任务技能包、workflow、playbook、gotcha、验证脚本和使用日志
Action 可执行动作，例如发送企微询问、创建 knowledge card、调用 Connector、reindex、更新看板
Writeback 动作结果、证据、review、失败、成本和权限决策写回审计或业务系统 ```
当前 P0 contract 已先把 object、relationship、rule、action、writeback event type 机器化，并新增 metadata、artifact、skill 和 provenance 的轻量扩展字段。artifact 和 skill 的完整运行态仍通过 docs、vault、task skill manifest、experiment registry 和 project status 表达；下一步再把这些制品的生命周期显式纳入 ontology registry。
当前 contract 规模：
- Architecture layer：3 个，覆盖 Evidence、Ontology、Runtime Projection。
- Layer relationship：3 个，覆盖 Evidence -> Ontology、Ontology -> Runtime Projection、Runtime Projection -> Evidence readback。
- Object：8 个，覆盖员工、任务、部门、政策、项目、knowledge card、reindex queue 和 connector callback ledger。
- Relationship：5 个，覆盖 owns、produces、queued_for 和 callback ledger audit。
- Rule：5 个，覆盖个人 consent、部门隔离、项目隔离、project knowledge card review 和 reviewed card reindex 生命周期。
- Action：7 个，覆盖 personal/department/project ask、finance policy review、project knowledge card review、promote、reindex。
- Writeback event type：4 个，覆盖 ask feedback、knowledge card review、reindex queue status 和 connector callback ledger。
- Metadata field：4 个，覆盖 source uri、permission scope、review status 和 provenance hash。
- Artifact type：4 个，覆盖 Markdown wiki、decision record、experiment report 和 knowledge card。
- Skill type：1 个，覆盖 task skill package。
- Provenance requirement：2 个，覆盖 Evidence -> Ontology 与 Ontology -> Runtime Projection。
- Ask Router binding：3 个，覆盖 personal、department、project 三类主动询问 route。
P0 不做大而全知识图谱，也不强行上图数据库。当前目标是让最小 contract 先进入 lint、eval 与工具治理：domain_topology_lint 会检查三段架构层、层间关系、metadata requirement、上下文库 runtime path、对象、关系、规则、动作和写回之间的引用，Domain Scope Eval 会要求 personal、department、project 三类基础 demo 都声明 ontology expectation，Ontology Tool Gateway Conformance 会检查 action、rule、object lifecycle 和 audited writeback 是否能约束工具调用。
当前 ontology action -> ToolPolicy 的最小 conformance 已完成，并且 OntologyToolGateway 已接入 personal、department、project 三类 Ask Router route、Knowledge Card review、promote 和 reindex queue 的本地执行路径。Ask Router binding 已进入 domain-topology.json，route_ask_request_guarded 会按 task/context-library 映射选择 ask action、对象状态和 throttle 对象。Ask Router 的对应对象状态、review/promote 与 queue worker 前后态已经写入 ontology-object-registry.json；External Connector Action writeback events 和 Connector Callback Ledger ontology event 已投影到 project status event timeline；owner registry 已支持显式组织目录优先、topology fallback。下一步是把企微通讯录、真实消息投递和回调事件接到同一 registry / delivery contract 后面，并把 worker retry 和 semantic review 接入同一 timeline。
相关背景见：Agentic Engineering 与本体论参考。
当前暴露的设计坑¶
这次实现暴露了一个重要问题：旧的 Tool Gateway 只支持 public/team/restricted 这类粗 scope，无法直接支持 person:*、dept:*、project:*。现在 SearchConnector Tool Gateway 已改为接受已认证用户的 namespaced scopes，但仍强制请求中的 allowed_scopes 必须是用户 scope 子集。
后续真实权限系统必须把 permission view 做成可审计策略，而不是只写在 JSON 文件里。