dsh-tang-governance

Readme

<p align="center">
  <img src=".github/assets/tang-governance-header.png" alt="Tang Governance — Three Departments and Six Ministries" width="100%">
</p>

<p align="center">
  <strong>A scale-aware, runtime-enforced multi-agent governance mode for DeepSeek Harness.</strong>
</p>

<p align="center">
  <a href="#english">English</a> · <a href="#简体中文">简体中文</a>
</p>

<p align="center">
  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-%5E22.19.0%20%7C%7C%20%3E%3D24-315e51">
  <img alt="License" src="https://img.shields.io/badge/license-MIT-3f7770">
</p>

<a id="english"></a>

# Tang Governance

Tang Governance is an independent npm bundle that adds a **Three Departments and Six Ministries** development mode to [DeepSeek Harness](https://www.npmjs.com/package/@deepseek-ai/dsh). It does not patch Harness source code.

The plugin turns a single coding request into an auditable workflow with requirement clarification, independent review, explicit user approval, responsibility-based execution, acceptance testing, and a user-controlled closure gate. Runtime checks enforce the important boundaries instead of relying on prompts alone.

> Inspired by the Tang dynasty's administrative structure; designed for modern AI-agent software delivery.

## Highlights

- **Scale-aware intake** — Zhongshu classifies the request as small, medium, or large and keeps simple tasks out of unnecessary full-process loops.
- **Clarification before drafting** — ambiguous requirements pause at a native choice interface before a solution is written.
- **Independent review and countersignature** — Menxia reviews the specification independently and may remand concrete issues.
- **Explicit user gates** — implementation cannot begin before approval; a case cannot close before final acceptance and user confirmation.
- **Uniform ministry routing** — Shangshu scans all six responsibility domains using the same rules, dispatching only the ministries that materially contribute.
- **Runtime-enforced boundaries** — delegation hierarchy, ministry roles, dependencies, verification, approval, and closure are validated by code.
- **Observable execution** — a responsive organization map, collapsible phase timeline, per-agent token usage, live status, and department records stay visible in one dashboard.
- **Stable model inheritance** — the Three Departments can be routed independently; the Six Ministries inherit Shangshu's provider and model while using task-appropriate reasoning effort.
- **Durable case files** — every task produces a structured dossier under <code>.tang/cases/&lt;case-id&gt;/</code>.
- **Workspace knowledge** — every new case receives a compact shared index, expands only relevant details or source dossiers on demand, and lets Zhongshu deduplicate reusable findings into one canonical document.
- **Recoverable stop semantics** — the user may stop work at any time without discarding completed artifacts.

## Product tour

<table>
  <tr>
    <td width="50%">
      <img src=".github/assets/screenshots/mode-selector.png" alt="Select Three Departments and Six Ministries mode">
      <br><strong>Native mode entry</strong><br>
      Select the governance mode directly from the Harness preset menu.
    </td>
    <td width="50%">
      <img src=".github/assets/screenshots/governance-dashboard.png" alt="Governance dashboard and execution timeline">
      <br><strong>Organization map + live trace</strong><br>
      Department state, routing controls, real calls, phases, and token usage share one responsive view.
    </td>
  </tr>
  <tr>
    <td width="50%">
      <img src=".github/assets/screenshots/requirement-clarification.png" alt="Requirement clarification dialog">
      <br><strong>Clarify before planning</strong><br>
      Zhongshu asks task-specific questions before drafting when the original request is ambiguous.
    </td>
    <td width="50%">
      <img src=".github/assets/screenshots/approval-review.jpg" alt="Countersigned proposal review">
      <br><strong>Reviewable approval gate</strong><br>
      The countersigned Markdown proposal is rendered in a dedicated approval workspace.
    </td>
  </tr>
  <tr>
    <td width="50%">
      <img src=".github/assets/screenshots/department-records.png" alt="Department execution records">
      <br><strong>Auditable department records</strong><br>
      Department cards expose chronological stages, evidence, and final status without leaving the dashboard.
    </td>
    <td width="50%">
      <img src=".github/assets/screenshots/closure-report.jpg" alt="Final closure report">
      <br><strong>User-controlled closure</strong><br>
      Acceptance evidence, artifacts, risks, and the chronicle remain reviewable before the case is closed.
    </td>
  </tr>
</table>

## Installation

Requirements:

- Node.js <code>^22.19.0 || &gt;=24</code>
- DeepSeek Harness <code>0.1.1-rc.2</code> or a compatible <code>0.1.x</code> release

Install from a local checkout:

~~~bash
git clone https://github.com/Ruszero01/dsh-tang-governance.git
cd dsh-tang-governance
pnpm install
pnpm run check
dsh plugin --profile web add link:.
dsh web --no-open
~~~

Open <code>http://127.0.0.1:3080</code> and select the mode for a new task.

On first launch, the plugin copies the installed Harness **Standard mode** through the public Agent Preset API and appends its governance tools. Shell, file operations, skills, goals, plans, subagents, and workflow primitives therefore follow the installed Harness version rather than a frozen source copy.

## Workflow

~~~text
User request
    ↓
Zhongshu — intake, scale, clarification, requirements, draft
    ↓
Menxia — independent review and executable specification
    ↕
Zhongshu + Menxia countersignature
    ↓
User approval gate
    ↓
Shangshu — phased plan and uniform Six-Ministry scan
    ↓
Selected Ministries — implementation, infrastructure, data, interfaces, or verification
    ↓
Menxia — final acceptance
    ↓
Zhongshu — final report, chronicle, and reusable knowledge distillation
    ↓
User closure gate
~~~

### Stage ownership

| Stage | Owner | Result |
|---|---|---|
| Intake | Zhongshu | Understand the original request, classify its scale, and ask only blocking questions. |
| Requirements & draft | Zhongshu | Write decision-level requirements and a solution draft without prescribing function-level patches. |
| Independent review | Menxia | Validate scope, risks, acceptance criteria, and produce the final executable specification. |
| Countersignature | Zhongshu + Menxia | Agree on the same scale and specification; remand only concrete unresolved issues. |
| Approval | User | Approve, remand with feedback, or cancel before any execution department is created. |
| Execution planning | Shangshu | Write <code>05-phased-development.md</code>, scan every ministry domain, record assignments and omissions, and order dependencies. |
| Ministry execution | Selected ministries | Produce bounded code, configuration, documentation, measurements, or independent evidence. |
| Acceptance | Menxia | Verify the approved specification and phased plan; remand failures to Shangshu. |
| Reporting | Zhongshu | Write the case-local report and chronicle, then upsert only reusable, source-cited findings into the workspace knowledge base. |
| Closure | User | Optionally request task-specific manual checks, then close, remand, or cancel. Remand feedback is automatically returned to Zhongshu; the coordinator only relays its questions and schedules the required follow-up. |

Task scale is a **soft planning signal**, not a hard token ceiling. Small requests should stay compact, while difficult work may expand when evidence or implementation requires it. Only explicit user or deployment configuration sets <code>maxTokens</code>.

## Six Ministries

Shangshu applies the same matching procedure to all six departments. No ministry is preferred, mandatory, exempt, or used as a generic fallback.

| Ministry | Domain | Owns | Does not own |
|---|---|---|---|
| Personnel / 吏部 | <code>repository-governance</code> | Repository reconnaissance, module ownership, task decomposition, dependencies, and handoff order | Product implementation or test approval |
| Revenue / 户部 | <code>data-dependencies</code> | Data and state models, migrations, dependency resources, performance impact, and related implementation | Unrelated product features or final acceptance |
| Rites / 礼部 | <code>interfaces-documentation</code> | API/UI contracts, compatibility, accessibility, documentation, user experience, and related implementation | Unrelated infrastructure or final acceptance |
| War / 兵部 | <code>application-code</code> | Product behavior, core application code, refactoring, and code migration | Self-approval or default build/release work |
| Justice / 刑部 | <code>quality-security</code> | Independent testing, reproduction, security and permission review, and regression verification | Implementing the feature currently under independent review |
| Works / 工部 | <code>infrastructure-release</code> | Build systems, development tooling, infrastructure, integration, packaging, deployment, and release | Generic product implementation or replacing independent verification |

Shangshu is not a seventh implementation agent. It owns scheduling, dependency coordination, evidence collection, and phase progression. Every ministry is either assigned concrete work or receives a specific omission reason. For code-changing phases, every implementation assignment must be covered by an independent Justice verification dependency.

## Runtime guarantees

The plugin enforces these rules in code:

- The root coordinator may create only the Three Departments.
- Only Shangshu may create the Six Ministries.
- Zhongshu, Menxia, and the Six Ministries cannot delegate further.
- Shangshu must register a structured phase plan before dispatching ministries.
- Every assignment references a matching department, role, reasoning effort, deliverable, verification method, and dependency set.
- Failed dependencies do not unlock downstream assignments.
- A successful approval result and a subsequent <code>user-approval: passed</code> milestone are both required before Shangshu can be created.
- <code>tang_submit_final_report</code> requires a successful <code>menxia-acceptance: passed</code> milestone.
- Built-in closure decisions and duplicate verification options are filtered safely so a completed run is not failed by redundant model output.
- The plugin uses public Harness extension points and does not depend on private <code>experimental/agent-team</code> packages.

## Model routing

The organization view can set provider, model, and reasoning effort for Zhongshu, Menxia, and Shangshu. Settings are stored in the Harness Settings namespace <code>tang-governance</code> and applied through the public request-routing waterfall.

The Six Ministries never choose independent models. They inherit Shangshu's current provider, model, and explicit <code>maxTokens</code>; Shangshu selects task-appropriate reasoning effort for each registered assignment. Unsupported reasoning levels fall back to the model's declared default instead of failing the dispatch.

Optional deployment defaults can be added to <code>.agent-presets/tang/agent.cordis.yml</code> under Harness Home:

~~~yaml
- id: tang-governance-tool
  name: 'dsh-tang-governance/tool'
  config:
    autoDispatch: true
    subagentProvider: spawn
    offices:
      zhongshu:
        provider: deepseek-official
        model: deepseek-v4
        reasoningEffort: high
        maxTokens: 16000
      menxia:
        provider: deepseek-official
        model: deepseek-v4
        maxTokens: 16000
      shangshu:
        provider: deepseek-official
        model: deepseek-v4
~~~

<code>autoDispatch</code> defaults to <code>true</code>. When disabled, the first request is no longer forcibly dispatched before the coordinator's first model call.

## Case dossier

Each case uses the following durable layout:

~~~text
.tang/
  config.json
  workspace-knowledge.md
  cases/<case-id>/
    01-requirements.md
    02-draft-solution.md
    03-review.md
    04-spec.md
    05-phased-development.md
    06-final-report.md
    07-chronicle.md
~~~

The phased plan records objectives, changed surfaces, boundaries, dependencies, ministry deliverables, verification, risks, checkpoints, and rollback. Function bodies and exact patches remain implementation decisions for the selected ministry.

<code>workspace-knowledge.md</code> is the sole cross-case knowledge source. Its compact index is injected at intake; agents expand selected entries and their cited case artifacts only when needed. Stable semantic keys merge corrections and new evidence instead of creating duplicate notes. Case timelines remain in <code>07-chronicle.md</code>; the shared document keeps only reusable decisions, constraints, patterns, pitfalls, and verification lessons with source case IDs.

## Contributing

Contributions are welcome — code, docs, tests, and reports. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first. Security vulnerabilities should be reported privately per [SECURITY.md](SECURITY.md).

---

<a id="简体中文"></a>

# 三省六部治理插件

三省六部治理插件是面向 [DeepSeek Harness](https://www.npmjs.com/package/@deepseek-ai/dsh) 的独立 npm Bundle，不修改 Harness 源码。

它把一条开发需求组织成可审计的智能体协作流程：需求澄清、独立审议、用户审批、按职责执行、最终验收、结案汇报与用户确认。关键边界由运行时校验，不只依赖提示词约束。

> 以唐代三省六部制度为灵感，为现代 AI Agent 软件交付提供清晰的职责分离与治理机制。

[返回英文](#english) · [查看产品截图](#product-tour)

## 核心特性

- **按量级受理**：中书省只判断任务量级，避免简单需求运行冗长流程。
- **起草前澄清**：需求存在阻塞性歧义时，先通过原生选择界面询问用户，再继续起草。
- **独立审议与会签**：门下省独立审查规格，并可针对具体问题封驳。
- **明确的用户门禁**：批准前不能进入执行，终验和用户确认前不能结案。
- **六部统一扫描**：尚书省按相同规则扫描六个职责域，仅调度能产生实际贡献的部门。
- **运行时职责约束**：派发层级、部门角色、依赖、独立验证、审批与结案均由代码校验。
- **可视化执行**：响应式架构图、可折叠阶段时间线、部门记录、实时状态和 Token 统计集中展示。
- **稳定模型继承**：三省可分别路由模型，六部统一继承尚书省的 provider 和 model，再按任务调整思考等级。
- **持久化案卷**：每个任务在 <code>.tang/cases/&lt;case-id&gt;/</code> 下留下结构化文档。
- **工作区知识案卷**：新案只预载共享索引，按需展开相关详情与原案证据，并由中书省将可复用结论去重写入唯一知识源。
- **可恢复叫停**：用户可随时叫停任务，同时保留已经完成的产物与证据。

## 安装

环境要求：

- Node.js <code>^22.19.0 || &gt;=24</code>
- DeepSeek Harness <code>0.1.1-rc.2</code> 或兼容的 <code>0.1.x</code> 版本

从本地仓库安装：

~~~bash
git clone https://github.com/Ruszero01/dsh-tang-governance.git
cd dsh-tang-governance
pnpm install
pnpm run check
dsh plugin --profile web add link:.
dsh web --no-open
~~~

打开 <code>http://127.0.0.1:3080</code> 即可开始使用。

新建任务时选择 **三省六部模式**。

插件首次启动会通过公开的 Agent Preset API 复制当前 Harness 安装版本的“标准模式”，再附加治理工具。因此 Shell、文件操作、Skills、目标、计划、子 Agent 和工作流等基础能力会跟随 Harness 版本更新，不会锁死在插件开发时的源码副本。

## 治理流程

~~~text
用户需求
  ↓
中书省：受理、量级判断、澄清、需求与草案
  ↓
门下省：独立审议与可执行规格
  ↕
中书省 + 门下省会签
  ↓
用户审批门
  ↓
尚书省：阶段计划与六部统一扫描
  ↓
按需启用六部：实现、数据、接口、基础设施或独立验证
  ↓
门下省最终验收
  ↓
中书省最终报告、史官记录与经验沉淀
  ↓
用户结案门
~~~

| 阶段 | 负责人 | 产出与约束 |
|---|---|---|
| 受理 | 中书省 | 理解原始需求、判断量级，只询问阻塞性问题。 |
| 需求与草案 | 中书省 | 编写决策层需求和方案，不预先规定函数级补丁。 |
| 独立审议 | 门下省 | 审查范围、风险和验收标准，形成最终可执行规格。 |
| 两省会签 | 中书省、门下省 | 对同一量级与规格达成一致，只针对实际未决问题封驳。 |
| 用户审批 | 用户 | 批准、附意见驳回或取消；批准前不创建执行部门。 |
| 执行规划 | 尚书省 | 编写 <code>05-phased-development.md</code>，扫描六部职责、记录派发与省略理由、排序依赖。 |
| 六部执行 | 按需选择的部门 | 交付有边界的代码、配置、文档、度量结果或独立证据。 |
| 最终验收 | 门下省 | 按批准规格和阶段计划验收，失败则退回尚书省。 |
| 奏报 | 中书省 | 根据真实执行和验收证据编写本案报告与史官记录，再将有复用价值且标明来源的知识合并到工作区知识案卷。 |
| 结案 | 用户 | 可先要求任务相关的手动检查，再确认、驳回或取消。驳回意见由运行时自动交回中书省，协调器只转交其澄清问题并调度必要的后续流程。 |

任务量级是用于精简规划的**软性信号**，不是固定 Token 上限。简单任务应保持紧凑，复杂任务可根据证据、实现和验证需要扩展。只有用户或部署配置显式设置的 <code>maxTokens</code> 才会成为请求上限。

## 六部职责

尚书省使用同一匹配流程扫描六部。不存在默认优先、强制启用、豁免或兜底部门。

| 部门 | 职责域 | 负责 | 不负责 |
|---|---|---|---|
| 吏部 | <code>repository-governance</code> | 仓库勘察、模块归属、任务拆分、依赖和交接顺序 | 产品实现、测试放行 |
| 户部 | <code>data-dependencies</code> | 数据与状态模型、迁移、依赖资源、性能影响及相关实现 | 无关业务功能、最终验收 |
| 礼部 | <code>interfaces-documentation</code> | API/UI 契约、兼容性、无障碍、文档、用户体验及相关实现 | 无关基础设施、最终验收 |
| 兵部 | <code>application-code</code> | 产品功能、核心代码、重构与代码迁移 | 自我验收、默认承担构建发布 |
| 刑部 | <code>quality-security</code> | 独立测试、缺陷复现、安全权限审计、回归验证 | 实现自己正在验收的功能 |
| 工部 | <code>infrastructure-release</code> | 构建系统、开发工具、基础设施、集成、打包、部署发布 | 兜底业务开发、替代刑部验证 |

尚书省不是第七个实现 Agent，只负责调度、依赖协调、证据收集和阶段推进。每一部都必须被派发实际任务或记录具体省略理由。任何修改代码的阶段，其实现任务都必须由独立的刑部验证任务覆盖。

## 运行时保证

插件通过代码强制执行以下规则：

- 顶层协调器只能创建三省。
- 只有尚书省可以创建六部。
- 中书省、门下省和六部不能继续派发。
- 尚书省必须先登记结构化阶段计划，再派发六部。
- 每项任务都必须匹配部门、角色、思考等级、交付物、验证方法和依赖。
- 失败的依赖不会解锁后续任务。
- 创建尚书省前，必须同时存在成功的用户审批结果和随后记录的 <code>user-approval: passed</code> 里程碑。
- <code>tang_submit_final_report</code> 只有在 <code>menxia-acceptance: passed</code> 后才能调用。
- 内置结案选项和重复验证选项会被安全过滤，不再因为冗余模型输出让已完成流程显示失败。
- 插件只使用 Harness 公开扩展点，不依赖私有的 <code>experimental/agent-team</code> 包。

## 模型路由

组织架构图可分别设置中书省、门下省和尚书省的 provider、model 与 reasoning effort。设置保存在 Harness Settings 的 <code>tang-governance</code> 命名空间，并通过公开请求路由生效。

六部不设置独立模型，始终继承尚书省当前的 provider、model 和显式 <code>maxTokens</code>；尚书省只为具体任务选择合适的思考等级。不支持的 reasoning level 会回退到模型声明的默认值，不再导致派发失败。

可在 Harness Home 的 <code>.agent-presets/tang/agent.cordis.yml</code> 中设置部署默认值：

~~~yaml
- id: tang-governance-tool
  name: 'dsh-tang-governance/tool'
  config:
    autoDispatch: true
    subagentProvider: spawn
    offices:
      zhongshu:
        provider: deepseek-official
        model: deepseek-v4
        reasoningEffort: high
        maxTokens: 16000
      menxia:
        provider: deepseek-official
        model: deepseek-v4
        maxTokens: 16000
      shangshu:
        provider: deepseek-official
        model: deepseek-v4
~~~

<code>autoDispatch</code> 默认为 <code>true</code>。关闭后，运行时不再在协调器第一次模型请求前强制派发原始需求。

## 案卷目录

每个任务使用以下持久化结构：

~~~text
.tang/
  config.json
  workspace-knowledge.md
  cases/<case-id>/
    01-requirements.md
    02-draft-solution.md
    03-review.md
    04-spec.md
    05-phased-development.md
    06-final-report.md
    07-chronicle.md
~~~

阶段计划记录目标、变更面、边界、依赖、六部交付物、验证、风险、检查点与回滚。函数实现和具体补丁由被选中的执行部门自行决定。

<code>workspace-knowledge.md</code> 是同一工作区唯一的跨案知识源。新案受理时只注入精简索引，确有相关经验时再按知识 ID 展开详情，必要时继续读取条目引用的原案文件。稳定语义键用于合并修正和新增证据，避免重复记录；执行流水仍留在各案 <code>07-chronicle.md</code>，共享文档只保留带案卷来源的可复用决定、约束、模式、踩坑和验证经验。

## 参与贡献

欢迎任何形式的贡献——代码、文档、测试与问题反馈。请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)；安全漏洞请按 [SECURITY.md](SECURITY.md) 私下报告。

## License

[MIT](LICENSE)