信息环境治理 ccneedb/dsh-information-environment-governance

信息环境治理（IEG）

状态：原型，在模型支撑的关卡通过之前仅做维护。目前只有作者本人使用。未发布到 npm。

IEG 是 DeepSeek Harness 的附加项目治理层。 它治理智能体工作所处的信息环境。该术语的规范定义、完整定位与权威范围见 PRODUCT-SPEC.md §1；本 README 只链接过去，不再复述。

状态：原型，尚未达到生产可用。 包名为 dsh-information-environment-governance 0.15.1 —— 可发布且已验证，但尚未发布 —— 发布目标也未定。行为改进（Gate C）与信息完整性（Gate D）为受阻 / 未验证 —— 证据不足；打包（Gate I）为通过 —— 证据完整。不建议用于工作配置档。当前数字见 MAINTENANCE-HANDOFF.md §3–§4；另见状态。

概览

这是什么？ 面向 DSH 编码智能体的信息环境治理：一段附加提示词，加上确定性的运行时关卡，以 dsh-information-environment-governance 插件的形式交付。它不是系统提示词的替代品，不是第二个智能体身份，不是通用的提示词改进器，也不是通用安全层。

它治理什么？

- 项目约束；
- 信息 / 文档的生命周期与完整性；
- 工作区整洁，仅限直接支撑信息环境的部分。

它不治理什么？

- 通用 AI 安全 / 安保；
- 沙箱；
- 授权；
- 用户注意力优化。

给谁用？ 依赖编码智能体做专业工作、但未必有完整软件工程背景的用户。

产品主张

目标不是让智能体「更聪明」，而是让项目环境更清晰、更一致，让智能体和用户随时间推移都更容易理解它。

这是预期收益，不是保证 —— 既不保证可靠性，也不保证模型能力更优。实际问题在于：项目会悄悄变成智能体和用户都无法再理解的东西 —— 那个「难以维护的烂摊子」，起初不过是几个图方便建的文件。即便你对项目方向的把握变得模糊，一个维护良好的项目环境也能为智能体重建项目上下文提供更干净的基础。

中文说明

信息环境治理（Information Environment Governance，简称 IEG） 是为 DeepSeek Harness 上的编码智能体提供的一层 附加治理。它治理的是智能体所处的信息环境（Information Environment）：智能体在项目中持续接触、依赖、修改或继承的持久化信息与项目约束。

治理什么

- 项目约束：目标、范围、术语、约束、当前阶段；
- 信息与文档的生命周期与完整性：存在性、状态、权威性、来源、替代关系、可检索性；
- 工作区整洁（workspace hygiene）——仅限直接支撑信息环境的部分。

不治理什么

- 通用的 AI 安全 / 安全防护；
- 沙箱（sandboxing）；
- 授权（authorization）；
- 用户注意力优化（user-attention optimization）。

面向谁：把编码智能体用于专业工作的用户，不要求具备完整的软件工程背景。

核心信息：目标不是让智能体“更聪明”，而是让项目环境随时间保持更清晰、更一致，更容易被智能体和用户理解。这是期望收益，不是可靠性保证。

即使项目方向的把握变得模糊，一个维护良好的项目环境也能为智能体重建项目上下文提供更干净的基础。

本项目的工作语言与权威文档为英文，本节仅为面向中文读者的简要说明；术语与产品边界以英文文档为准（PRODUCT-SPEC.md §1）。

目录

本仓库既是项目文档，也是插件的工作原型。

| 文档 | 读者 | 用途 |
| PRODUCT-SPEC.md | 人 + 智能体 | 定位、权威定义与范围、两个治理入口、目标、需求、成功标准——IEG 是什么的唯一事实来源 |
| ARCHITECTURE-SPEC-AGENT-REFERENCE.md | 实现智能体 | 架构、模块契约、图示、运行时集成、兼容性模型。Part A 是经源码核实的宿主集成、其差异与残留假设。Part B 是目标设计、验收矩阵（§32）与阶段计划 |
| MAINTENANCE-HANDOFF.md | 维护者 | 维护状态记录：当前状态与数字（§3–§4，唯一事实来源）、阻塞项、待办清单、流程坑点、工作区布局，以及命名/撤回历史 |
| TESTING.md | 志愿者 | 志愿者流程：安装、首次试用、A/B 检查、偏差上报 |
| SECURITY.md | 所有人 | IEG 不是什么、已接受的限制（唯一事实来源）、范围外清单，以及如何上报漏洞 |
| CONTRIBUTING.md | 贡献者 | 前置条件、要运行的检查（唯一事实来源）、项目规则 |
| IMPLEMENTATION-VALIDATION-HANDOFF.md | 智能体 | 已退役——指向 §32 的验收门槛与历史构建顺序 |
| docs/DOCUMENTATION-INDEX.md | 所有人 | 文档清单与唯一事实来源映射 |
| .github/ISSUE_TEMPLATE/ | 用户 + 维护者 | 偏差报告所用的缺陷报告与功能请求表单 |
| 仓库根目录（package.json、cordis.patch.yml、src/、lib/、bin/ieg） | 实现智能体 | 可用的 dsh-information-environment-governance 包：清单、内核、三个模块、dsh-ieg 终端界面，以及验证链。根目录就是包——没有 plugin/ 子目录 |
| eval/ | 评估智能体 | 行为评估与端到端评估：评估框架、预置场景，以及沙箱运行 |

IEG 治理什么

IEG 有两个治理入口：

1. 项目约束治理 —— 让项目目标、范围术语、约束和当前阶段保持明确，并区分声明的理解与实际行为的一致性。
2. 信息 / 文档治理 —— 让项目信息的状态保持明确（是否存在、状态、权威性、来源、取代关系、可检索性），并治理承载这些信息的文档。工作区卫生是这个入口内部的执行机制，不是独立系统。

三个主要领域在范围内：

1. 项目约束 —— 目标、范围、术语、约束、当前阶段。
2. 信息状态 —— 权威性、有效性、来源、取代关系、生命周期状态。
3. 持久工作区 —— 文档、产物、源码/配置，以及生成的文件。

明确不在范围内

以下内容不是 IEG 的关注点，未来任何功能都不得漂移到这些领域：

- 通用 AI 安全或安保；
- 沙箱；
- 授权；
- 用户注意力优化（已退役 —— 该能力在 0.7.0 中撤回；历史记录见 MAINTENANCE-HANDOFF.md §13.2）；
- 无关的智能体行为管理。

未来任何功能都必须证明与信息环境治理有直接关联。这条边界的权威表述见 PRODUCT-SPEC.md §1 和 §4；安全后果见 SECURITY.md。

模块（3 个，默认全部启用）

| 模块 | 失败类别 | 关注点 |
| project-governance | FC-2.1 | 项目定位、范围、术语，以及约束漂移 |
| information-integrity | FC-2.3 | 复用已知无效或已被取代的信息 |
| workspace-governance | FC-2.2 | 未经授权改动持久工作区 |

原 user-attention 模块和失败类别 FC-2.4 已在 0.7.0 中移除，归类为「不在范围内 / 由外部解决」。它们不是当前能力；撤回记录作为历史保存在 MAINTENANCE-HANDOFF.md 和 ARCHITECTURE-SPEC-AGENT-REFERENCE.md 的 Part B 中。

接口：dsh-ieg 终端命令

受支持的接口是一个终端命令 dsh-ieg，在 Debian shell 中运行。不带参数运行会打印用法；每条命令也都能配合标志非交互运行，因为 CI 和脚本会调用它。入口文件是 bin/ieg。

dsh-ieg # usage (there is no interactive menu)
dsh-ieg prompt # print the effective prompt, its version and byte count
dsh-ieg prompt edit # $EDITOR on a temp copy of the effective text; validate; store
dsh-ieg --help / --version
这里没有安装、更新、卸载或生命周期入口：插件无法自行安装，所以 §Install 只给出两条官方入口路径。Batch 5 移除了原先的 install/update/uninstall 命令、start/pause/restart/exit 控制面和交互式菜单，因此 prompt 管理就是全部接口——在行配置里写 enabled: false，即可为某个配置档关闭治理。

提示词文本存放在 prompt.md，路径优先取 $IEG_PROMPT_FILE，否则取 <state-dir>/ieg/prompt.md，其中 <state-dir> 优先取 $XDG_STATE_HOME，否则取 ~/.local/state。每个候选文本都走同一套内核校验，插件处理配置提供的覆盖时用的也是这套内核（不允许 {{ }}，除非开启 allowOverBudget，否则受字节上限约束；被拒绝时保留原文本并打印原因），并且每次组装都会重新解析，所以改完即生效，无需重新挂载。优先级为：运维方 prompt.md > 配置 prompt.file（当 prompt.mode: replace 时）> prompt.append > 编译内置默认值。

插件贡献一个追加式提示词段落 ieg:governance（order: 8500、interpolate: false、从不设置 complete）和六个工具——record_orientation、record_information、confirm_terminology 和 confirm_information，外加只读的 ieg_status 与 maintain_environment。两个确认工具经宿主的审批服务把关，所以模型无法自行提供用户的授权。在 PROMPT_VERSION 0.6.0 下，编译后的段落为 2,840 字节，上限为 2,945 字节。它通过 ieg:status 运行时上下文行和 ieg. 诊断码报告自身状态。完整运行时细节见 ARCHITECTURE-SPEC-AGENT-REFERENCE.md Part B。

术语治理

IEG 维护一份项目本地词汇表，作为持久化的项目状态：canonicalTerm、definition、aliases[]、status（PROVISIONAL | CONFIRMED | DEPRECATED | CONFLICTED）、source、scope、confirmedByUser、confidence 和 supersedes[]。在环境勘察阶段捕获的术语以暂定且推断状态进入；只有用户明确陈述，术语才会变为已确认。

这是语义对齐，不是语言警察：无害的别名静默接受，歧义会浮出水面，冲突只上报，不靠选定某个含义来解决。优先级模型及其不变式——推断条目不会仅因被持久化就成为不容置疑的权威——见 MAINTENANCE-HANDOFF.md §3。

维护轮次

IEG 还会维护环境，而不只是给动作把关。有一个可手动触发的轮次 maintain_environment，它盘点工作区的持久化产物（权威规格、实现文档配置、工作笔记、生成物、历史、临时和未知），诊断重复、过时和声明的漂移，并返回建议动作从固定词表中取值——KEEP | MERGE | UPDATE | REPLACE | DEPRECATE | REMOVE | LEAVE_UNCHANGED | REQUIRES_REVIEW——每项都附带理由和置信度。

它只提议，从不执行。 这个工具在设计上就是只读的，每个破坏性提议都需要人来明确决定。用 changed 把它指向某处具体改动，它还会做一致性核对：哪些其他产物提到了这个主题，它们陈述的哪些事实已经过时，以及哪些它无法定论。

运行时用宿主自己的轮次计数来统计直接用户指令批次；内部步骤、工具调用和生成的上下文在设计上不计入。计数到七时，它在运行时上下文中标记维护到期，并重置计数器。

未实现的内容写在 MAINTENANCE-HANDOFF.md §3——特别是超出已声明状态的跨文档矛盾检测，它被列为未来能力，而不是现有承诺。

安装

IEG 是 DSH 插件。它由宿主自己的插件安装器安装，之后才由 dsh-ieg 管理。这是两个独立步骤：dsh-ieg 由包本身提供，所以它无法引导安装这个包。在干净机器上，直接敲 dsh-ieg 根本不在你的 PATH 里： console
$ dsh-ieg prompt
bash: dsh-ieg: command not found

请安装到一次性配置档，绝不要装进你依赖的配置档。

1. 标准安装——DSH 原生方式（推荐）

DSH 可以从注册表包名、绝对路径、git 地址或 tarball 安装插件。这是首次安装的路径： bash

from the repository (the repository root IS the package)

dsh plugin --profile <your-test-profile> add \
https://github.com/ccneedb/dsh-information-environment-governance

confirm the bundle row composed

dsh --profile <your-test-profile> --dump-config | grep -A3 'id: ieg'

DSH Web UI 的插件安装通过「Git repository」字段提供同样的仓库 URL 路径——这是同一机制的图形化形式。

2. npm 包

这个包可发布且已验证，但尚未发布。注册表名 dsh-information-environment-governance 目前无人占用，所以首次发布是维护者的动作，仍要等 Gates C 和 D 以及发布目标决定（Status）。在那之前，从注册表 npm install 无法解析；请在本地构建并安装确切的产物： bash
npm pack # builds exactly what npm would publish
dsh plugin --profile <your-test-profile> add \
"file:./dsh-information-environment-governance-<version>.tgz"

打包产物恰好包含运行时——lib/、bin/ieg cordis.patch.yml、package.json、README.md、LICENSE、CHANGELOG.md——不含 src/、test/、eval/、docs/。包级配置细节见 docs/PACKAGE-REFERENCE.md。

3. 开发与恢复要开发 IEG 本身，或恢复配置档： bash
dsh plugin --profile <your-test-profile> add "file:/path/to/this/repository" # a checkout
dsh plugin --profile <your-test-profile> remove dsh-information-environment-governance

发布 tarball 附在 GitHub release 上；它是开发者/恢复用的来源，不是普通用户的安装路径。

dsh-ieg 提示词命令行

dsh-ieg 只管理已安装 IEG 的提示词，别的什么都不做。pnpm 会把它装进配置档里、和包放在一起，而不是装到你的 PATH 上，所以可靠的调用方式是配置档内的本地二进制： bash <DSH_HOME>/profiles/<your-test-profile>/node_modules/.bin/dsh-ieg prompt

想要一个稳定的命令，可以用 npm 全局安装这个包（npm install -g dsh-information-environment-governance，发布之后可用），或者通过 npx dsh-ieg … 调用。它有两个命令：prompt（查看生效文本、版本号和字节数）和 prompt edit（校验编辑后的副本并保存）。它从不安装任何东西。

升级

常规升级会重新执行宿主对配置档的安装；正是这一步重新解析并重新链接包，dsh-ieg 不参与： bash
dsh plugin --profile <your-test-profile> add <the same source you installed from>
dsh --profile <your-test-profile> --dump-config | grep -A3 'id: ieg' # still composes
<DSH_HOME>/profiles/<your-test-profile>/node_modules/.bin/dsh-ieg prompt # the effective text

首次安装、升级、开发者/恢复用的都是同一条 DSH 原生命令；变的只是来源*（仓库 URL、registry 名、checkout 或 tarball）。

首次使用前有两点值得注意：

- 配置档在安装时链接插件，所以来源一变就要重新安装，否则你跑的还是旧代码；
- IEG 默认 workspace.policy: ask 和 overlapCheck: ask，在没有审批通道的组合里会失败关闭。在无头会话或智能体委派的会话里没人应答，闸门就会拒绝写入——见 MAINTENANCE-HANDOFF.md §7。首次试用建议用 workspace: { policy: allow, overlapCheck: ask, protectedPaths: [...] }，并保留非侵入式的 requireBeforeMutation: false 默认值。

要求：Debian/Linux（受支持的环境）、Node.js >= 20，以及一套 DeepSeek Harness 安装。Shell 治理只针对 Bash；PowerShell 和其他平台明确不支持。声明的 peer 范围是 >=0.2.1-rc.2 <0.3.0，dsh.compatibility.dshReleases 把这一条基线记为 verified；提交的基线已在 0.13.0 中针对已安装的 0.2.1-rc.2 宿主重新验证（section 顺序与宿主提示词哈希一致）。0.2.1-alpha.1 和 0.2.0-rc.2 基线已废弃，不再位于范围内，也不在发布映射中。注意，声明的范围是兼容性声明，不是已测版本清单：只验证了 0.2.1-rc.2 这一个发行版。见 MAINTENANCE-HANDOFF.md §3–§4。

志愿者测试

行为门槛离不开真实会话，没有真实会话就测不出来，所以志愿者是这个项目的瓶颈。志愿者流程只维护一份，放在 TESTING.md：用一个一次性配置档，做首次试用配置，做 A/B 对照检查，以及偏差报告里该记录什么。运行中的应用里，插件列表显示的是该应用实际运行的那个配置档里的 bundle，所以应用跑 web 时你往 ieg-test 里装，看起来和安装失败一模一样；scripts/check-install.sh 会端到端检查配置档，并打印出你处在哪种情况。

仓库结构 text README.md 本文件 PRODUCT-SPEC.md 定位、范围、目标、成功标准 ARCHITECTURE-SPEC-AGENT-REFERENCE.md 架构；Part A 已验证的宿主接缝 Part B 目标设计与 §32 门槛 IMPLEMENTATION-VALIDATION-HANDOFF.md 已废弃的指针，指向 §32 与构建顺序 MAINTENANCE-HANDOFF.md 当前状态与数字；维护注意事项 TESTING.md 志愿者安装、首次试用、偏差报告 SECURITY.md 边界、已接受的限制、报告方式 CONTRIBUTING.md 前置条件、检查项、项目规则 CODE_OF_CONDUCT.md Contributor Covenant 2.1 LICENSE MIT docs/ 文档索引与单一事实来源映射 scripts/ 仓库工具（check-install.sh、check-docs.sh、verify.sh） package.json / cordis.patch.yml DSH bundle 清单与补丁（根目录就是包） src/ 运行时的 TypeScript 事实来源 lib/ tsc 从 src/ 编译出的运行时（已提交） bin/ieg dsh-ieg 可执行 shim test/ test-support/ 单元、一致性、集成测试套件 eval/ 行为评估工具 .github/ CI、issue 表单、pull request 模板

文档 front matter 带 doc_type、owner、last_reviewed、status。version 是文档自身的修订号——它跟的是文档，不是包——plugin_version 若存在，则标明该记录描述的包版本。这条规则连同完整清单与单一事实来源映射，统一写在 docs/DOCUMENTATION-INDEX.md。

开发

前置条件、要跑的检查（typecheck、npm test、verify.sh check-docs.sh），而让项目保持可维护的规则只在 CONTRIBUTING.md §Running the checks 里维护一次。集成测试挂载真实的宿主服务；没有 DSH 安装时它们跳过（而不是失败）。用 IEG_DSH_PACKAGES 把加载器指向非默认安装；验证链遵循 IEG_VERIFY_HOME。报告任何问题前先读 SECURITY.md。

可运行的原型

仓库根目录就是一个可安装的 dsh-information-environment-governance 0.15.1（可发布且已验证，尚未发布），零运行时依赖，实现了上面的架构。它贡献一个增量提示词段落，并通过 agent/pre-step、tools/pre-execute、ctx.tools.guard 和 ctx.storageDomain 强制执行；它通过一行有界的运行时上下文状态，加上 record_orientation 和只读的 ieg_status 工具，报告自身状态；它还附带用于控制的 dsh-ieg 终端界面，以及针对 prompt.md 的 prompt / prompt edit 命令。运行时用 TypeScript 写在 src/ 下；lib/ 是提交进仓库的 tsc 构建产物（见 TYPESCRIPT-MIGRATION.md）。

证据链——按 CONTRIBUTING.md §Running the checks 运行——覆盖严格类型检查、完整测试套件（全部通过，无 todo、无 skip；当前数量见 MAINTENANCE-HANDOFF.md §3；单元提示词一致性，以及挂载真实 dsh-system-prompt、dsh-tools、dsh-fs-local 和 dsh-storage/dsh-storage-json/dsh-storage-domain 技术栈的集成测试），以及 scripts/verify.sh 的 24 项检查：真实安装进一个一次性配置档、组合出 ieg 行，并正面证明已安装的插件绑定了它的段落、监听器和工具——而且能可观测地吸收错误配置，而不是卸载。当前数量见 MAINTENANCE-HANDOFF.md §3。它尚未验证哪些内容，诚实清单见 docs/PACKAGE-REFERENCE.md。

行为效果由 eval/ 里的沙箱测试装置单独测量，它跑真实智能体试验，分别带治理段落和不带治理段落。当前提示词修订版没有有效测量： 早先的试验跑的是已撤回的提示词修订版，已作为被取代的结果删除，所以 eval/README.md 记录的是方法和待重跑，而不是被取代的数字。

状态

原型。尚未达到生产可用。

1. 门 C 和门 D 对当前的三模块提示词尚未测量——不作任何行为声明——打包（门 I）已通过——证据完整。门 C 需要一次由模型驱动的 eval/ 运行，评分标准事先冻结，且评判者看不到分组。门 D 需要同样类型的运行，用于信息完整性。被取代的测量结果直接删除，不做标注，因为过时的数字读起来仍像当前结论。
2. 决策待定，统一记录在 MAINTENANCE-HANDOFF.md §9：发布目标，以及任何 live-profile 推广。兼容性基线的重新采集（Q7）已在 0.13.0 关闭：唯一受支持的基线是 dsh 0.2.1-rc.2。控制状态文件及其按配置档划分的问题（Q8）已在 0.6.0 随控制平面一并撤回；现在没有需要划定范围的控制状态文件。
3. 包可以发布，但尚未发布。 private 已移除，打包产物已在干净的配置档下验证，registry 名称未被占用；发布本身就是发布动作，在 1 和 2 解决之前暂不执行。

当前版本、测试数量、验证结果和各道门的通过状态，统一维护在 MAINTENANCE-HANDOFF.md §3–§4，门表见 ARCHITECTURE-SPEC-AGENT-REFERENCE.md §32.1。

报告任务失败

偏差报告就是普通 GitHub issue。使用仓库的 .github/ISSUE_TEMPLATE/bug_report.yml 表单（能力请求用 feature_request.yml）—— 该写什么见 TESTING.md §6。

最重要的一步是 A/B 对照：先让智能体调用 ieg_status，再关闭 IEG（enabled: false；正确做法见 TESTING.md §4）跑同一个任务。这样能把 IEG 缺陷和宿主或模型缺陷分开 —— 这也正是门 C 和门 D 需要的测量。

架构声明（权威表述）

IEG 是 DSH 的增量式项目治理层。它稳定的行为策略通过一个系统提示词段落贡献；有状态和确定性的控制则使用 DSH 运行时中合适的接缝。

参与贡献

先读 CONTRIBUTING.md，了解前置条件、要跑的检查，以及让项目保持精简的规则 —— 只加一个提示词段落、用确定性执行代替提示词文本、零运行时依赖、不重复文档、apply() 永不抛异常、提示词改动必须注明来源。参与行为受行为准则约束。

许可证

MIT © 2026 IEG contributors。插件包在 LICENSE 携带同一许可证。

与 DeepSeek-AI 无隶属关系，也未获其背书。