DSH 个人本地 Agent 工作台改造记录：Token 审计、知识库、工具策略与 Git 仓库可视化- 惊觉

DSH 个人 Agent 工作台改造

1. 改造目标

这轮改造没有重写 DSH 的 Session、LanceDB、Embedding 或现有 Agent preset 核心，而是在已有插件、事件、projection 和 UI Slot 体系上增加个人工作台能力：

用户输入
  -> 模式策略与本地建议
  -> 上下文预算组装
  -> Agent Loop
  -> 工具执行与审批
  -> 校验 / 检查点
  -> Token、知识库与 Git 轨迹
  -> Session 持久化

核心验收标准不是承诺固定百分比的 Token 节省，而是：

简单问题不会无故进入工具循环。
长历史不会无限增长。
每次模型请求都能解释上下文来源。
工具权限和本机文件修改行为可控。
Web 和 CLI 仍能完成个人本地工作流。

首页总览

2. Personal Agent 模式策略

新增包：

packages/interaction/personal-agent/
@deepseek-ai/dsh-personal-agent

公共类型为 AgentMode 与 ModePolicy。策略同时定义工具、上下文、权限和预算上限：

type AgentMode = 'qa' | 'research' | 'coding' | 'execution'

interface ModePolicy {
  mode: AgentMode
  visibleTools: string[]
  maxSteps: number
  maxToolResultBytes: number
  maxContextTokens: number
  historyTurns: number
  knowledgeBase: 'off' | 'explicit'
  approval: 'ask' | 'never'
  sandbox: 'read-only' | 'workspace-write' | 'danger-full-access'
}

默认模式策略：

mode	默认工具	maxSteps	historyTurns	sandbox
qa	无编码工具	0	6	read-only
research	只读文件、搜索、网页、知识库	6	8	read-only
coding	读写、Shell、测试、Git、Skill	16	12	workspace-write
execution	按需开放媒体和本机执行能力	16	6	workspace-write

模式策略有两个执行边界：

请求边界： 在 agent/request-context 阶段过滤工具 schema、工具说明和历史上下文。
执行边界： 在 tools/pre-execute 阶段拦截实际工具调用，记录 agent/tool-denied。

因此，隐藏 schema 不是安全措施本身。即使模型通过 Skill 或历史消息发出模式外调用，执行层仍会拒绝。

模式切换写入 agent/mode，当前 turn 会固定 active mode，下一轮才使用新模式。子会话可以继承父会话的个人模式；旧 preset 会话在用户没有明确选择个人模式前保持原行为。

【截图占位 2：模式策略】

截图要求： 在输入栏打开模式菜单，截到四种模式和当前工具步骤上限；再输入“修改这个 TypeScript 文件”，截到本地建议编码模式的结果。截图应能体现建议没有触发模型请求。

个人模式

3. Context Budget 与 Token 账本

Agent Loop 在请求前触发新的 agent/request-context waterfall。它只改变本次发给模型的消息快照，不破坏 Session 的原始历史。

上下文处理顺序：

保留系统消息和当前用户请求。
根据模式保留最近若干轮。
按工具类型裁剪过大的工具结果。
去重重复工具结果、知识库内容和 Skill 目录。
按 Token 预算丢弃低优先级旧消息。
将输入 / 输出消息数、裁剪、去重和分项估算写入审计事件。

每个请求的 agent/request-context 会记录：

mode
maxSteps / usedSteps
inputMessages / outputMessages
droppedMessages / deduplicatedMessages
systemPromptTokens
toolSchemaTokens
historyTokens
knowledgeBaseTokens
skillTokens
toolResultTokens
estimatedInputTokens
outputBudgetTokens

供应商真实 usage 和本地上下文分项严格区分：前者用于账单，后者用于解释“为什么这个请求变大”。

Token轨迹总览

Token输入溯源

4. 知识库集成

知识库继续采用本机 LanceDB 与本地 Embedding 模型。对话输入栏新增 Session 级知识库选择：

一个会话可选择一个或多个知识库；
未选择或手动关闭时，请求不包含知识库正文；
研究和问答模式支持自动召回，编码模式默认不主动检索；
结果带知识库名、文档标题、分块编号和相似度；
使用 similarityThreshold、maxResultTokens、正文去重和 Token 预算限制结果；
失败写入 knowledge/retrieval，但继续回答。

知识库选择自身写入 knowledge/selection，通过 knowledgeSelection projection 恢复。知识库“处于启用状态”和“当前对话是否使用”不再混为一谈。

启用知识库

5. 工具目录、相似度与按需发现

Token 轨迹中新增工具与对话的本地词项相关度。它使用中英文词项、停用词和任务词映射做加权余弦匹配，展示：

工具名称和相似度百分比；
匹配词；
本步是否调用；
原始 schema 顺序或相似度排序。

该结果是本地估算，不是 Embedding 语义相似度，也不是模型调用概率，不会产生模型请求。

packages/preset/tool-discovery 增加了按需工具发现和 recoveryTools。它会：

保留当前模式允许的固定工具。
根据会话中的真实工具调用频次补足初始工具。
在模型调用 tool_search 后，按精确名称或词项搜索可允许的候选。
将工具选择原因写入 metadata，如 exact-name、lexical-match、safe-recovery。
在 schema 装配下游再次过滤，避免被模式禁止的工具重新注入。

工具相似度和选择依据

6. Git 工作区插件：从“看起来改好了”到可复核证据

6.1 插件挂载

新增只读插件：

packages/interaction/git-workspace/
@deepseek-ai/dsh-git-workspace

它已在 dsh-base Bundle 中默认挂载，相关配套位于：

packages/bundle/base/cordis.patch.yml
packages/bundle/base/package.json
packages/core/session/src/known-event-types.ts

插件和 Agent preset 是两个不同边界：Git 工作区插件负责采集仓库证据，不负责决定模型是否可以写文件；写入、删除、高风险命令仍由现有权限、沙箱和审批策略控制。

6.2 检查点事件

每次 turn/start 记录 before 检查点，每次 turn/end 记录 after 检查点，事件类型为：

agent/git-checkpoint

事件数据结构：

interface GitCheckpoint {
  turn: number
  phase: 'before' | 'after'
  cwd: string
  branch?: string
  status?: string
  diffStat?: string
  diff?: string
  error?: string
}

插件在当前 Session 的 cwd 下执行三条只读命令：

git status --short --branch
git diff HEAD --stat
git diff HEAD --no-ext-diff --unified=3

默认边界：

status  <= 24 KB
diffStat <= 4 KB
diff     <= 24 KB

超过上限时仅保留前段和“Git 输出已截断”标记；执行失败时把错误写入 error，并继续让会话完成。插件不执行 commit、add、reset、checkout、clean、push，也不修改工作区。

检查点任务是串行排队的，避免同一个 Session 在 turn 结束时并发执行多组 Git 读取。session/flush 会等待队列完成，确保页面加载时能拿到已经采集的检查点。

6.3 前端仓库视图

新增文件：

packages/client/ui-step-insight/src/client/GitWorkspaceView.tsx
packages/client/ui-step-insight/src/client/RepositoryView.tsx
packages/client/ui-step-insight/src/client/RepositoryFlow.tsx
packages/client/ui-step-insight/src/client/git-view.ts

Token 轨迹新增“仓库”视图。RepositoryView 从已加载的 Session 事件筛选 agent/git-checkpoint，GitWorkspaceView 再解析：

git status --short 的文件状态；
git diff --stat 的文件数、插入行、删除行；
最新 after 检查点的分支和 diff；
before / after 检查点时间顺序。

仓库页面的流程节点为：

仓库 -> 读取状态 -> 解析变更 -> 更新监视 -> 已读取检查点

这部分是证据展示，不是新的写操作入口。仓库视图显示“只读审计，不会自动提交或修改仓库”。

Token 轨迹中的“仓库”视图

请求详情中的 Git 工作区卡片

6.4 浏览器端仓库监视

RepositoryFlow 还提供浏览器本地保存的仓库监视入口。它支持输入地址、开启 / 关闭监视、刷新状态和显示提交时间线；公共仓库抓取目前以公开 GitHub HTTPS 地址为主。

需要区分两个来源：

本地 Agent 的真实工作区变化：来自 agent/git-checkpoint，由本机 Git 读取。
公共仓库的提交时间线：来自浏览器端对公开 GitHub API 的有限读取。

公共仓库监视不能替代本地工作区检查点，也不会把外部仓库内容自动注入模型上下文。

仓库监视和提交时间线

7. 推理内容与默认 preset

已完成的推理正文从普通聊天正文移动到 Token 轨迹“输出明细”，普通会话只显示简洁 Think 状态。这样聊天页面更适合阅读，轨迹页面更适合审计。

Web Bundle 配置为：

- id: agent-presets
  name: '@deepseek-ai/dsh-agent-presets'
  config:
    default: diaosi
    modeSelectionEnabled: false

standard、ptc、minimal、cordis 和自定义 preset 没有删除，仍通过“设置 -> Agent 预设”管理。已运行会话不会被强制切换，只有新会话使用新的默认值。

普通对话与输出明细的对比

设置页中的 Agent 预设

8. 事件、构建和测试

本轮新增或扩展的主要事件包括：

agent/mode
agent/request-context
agent/tool-denied
agent/git-checkpoint
knowledge/selection
knowledge/retrieval
task/created / planned / running / waiting-human
task/succeeded / failed / cancelled

审计类事件使用 ignorable: true，旧读取器遇到这些事件时可以安全跳过。Remote、事件目录、持久化 schema、配置目录和 TypeScript 路径同步更新。

已经覆盖的测试包括：

模式建议、schema 过滤和执行拒绝；
上下文裁剪、工具结果裁剪和当前用户请求保留；
知识库阈值、去重和 Token 预算；
工具发现匹配与安全恢复；
Git status / diff stat 解析；
仓库视图和仓库监视；
Bundle 是否默认挂载 Git 工作区插件。

验证命令：

pnpm run verify-cordis-config
pnpm run verify-tsconfig-paths
git diff --check

服务地址：

[http://127.0.0.1:3081/](http://127.0.0.1:3081/)

9. 设计边界

不做公开部署、多用户账号和云端任务队列。
不自动提交 Git，也不在仓库视图中提供危险写操作。
Token 分项是本地上下文解释估算，不能代替供应商账单。
工具相似度是词项相关度，不能解释为模型调用概率。
Git diff 有上限，超出后只展示截断结果。
知识库必须在当前对话显式选择，不把整个知识库注入系统提示词。
当前工作区可能存在大量未提交文件，发布截图时应选择范围清晰、不会泄露隐私的示例任务。

10. 总结

这一轮改造的重点不是增加更多按钮，而是把 Agent 的工作过程变得可解释：

模型看到了什么？ -> Token 轨迹
为什么出现这个工具？ -> 工具发现与相似度
知识库从哪里来？ -> 选择与召回审计
代码改了什么？ -> Git 前后检查点与 diff
当前是否允许这样做？ -> 模式、沙箱、审批

其中 Git 工作区插件是编码模式闭环的关键：它把一次任务前后的仓库状态持久化到 Session，再由仓库视图以只读方式展示。Agent 仍然不能绕过审批自动修改或提交，但用户可以直接复核变更文件、分支、增删行和 diff，而不必重新打开终端手工对照。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/2302_80329073/article/details/166230512

DSH 个人本地 Agent 工作台改造记录：Token 审计、知识库、工具策略与 Git 仓库可视化