# Workspace Context Debug Command

## Current Design

- UI 展示的 workspace context 百分比来自 ACP `UsageUpdate.used / UsageUpdate.size`，这是当前 session 的真实总量。
- ACP/OpenCode 当前只返回总量，不返回 system prompt、skills、knowledge、tool output、evidence 等内部来源分项。
- Backend 持有可归因的本地输入：静态 instructions、首次 prompt 的 dynamic workspace context、enabled workspace skills、workspace evidence/issues 文件、`messages_v2` 中持久化的 chat/tool payload、以及 `interaction_token_usage` 中最新 context 总量。
- Debug 维度必须是语义来源，不是 carrier：tool result 读了 evidence 就归 Evidence，读了 skill knowledge 就归 Skills & Knowledge，读了 cluster/issue meta 就归 Cluster & Alert Metadata。

## Risks

- 分项无法做到 OpenCode 内部精确归因，只能用 server 可见内容做估算。
- Workspace 文件存在不等于进入模型上下文；只有被 prompt 注入、skill 加载、或 tool/read 结果进入 chat history 的内容才可能贡献 context。
- `.opencode/.all-skills` 是候选技能缓存，不应计入 enabled skills 或 context 估算。

## Target Contract

- Canonical source of truth:
  - 总 context 使用量：最新 `interaction_token_usage.context_used/context_size`，排除 evidence postpass 等非 ACP session 记录。
  - 分项归因：backend 只读 workspace 文件和 DB 消息，按语义来源生成估算报告，不写 workspace、不触发 agent、不修改 session。
- Debug 输出必须同时显示：
  - 真实总量：`context_used/context_size/percent`。
  - 各语义来源估算：Evidence、Skills & Knowledge、Cluster & Alert Metadata、Agent/runtime instructions、Conversation、Attachment metadata 等。
  - 每个语义来源显示 estimated tokens、scaled tokens、percent of actual used context、bytes、item count。
  - Example 明细主列必须显示用户可读 item label（如 `Loaded skill: tidb-clinic-diagnosis`、`Read evidence summary: evidence_summary_for_agent.txt`），内部 `messages_v2/.../parts/N` 只作为 source_ref，不放进主表。
  - Example 明细需要显示 scaled tokens 和 Used %，让用户能看出单个 item 对已用 context 的占比。
  - Assistant thinking 只能统计 `messages_v2.parts` 中可见/持久化的 reasoning text；隐藏模型 reasoning 没有可归因来源，不能猜。
  - 明确说明估算边界：非 tokenizer 精确值，不能代表 OpenCode 内部缓存精确分配。
- 不引入读路径写入，不清理旧 workspace，不做 UI 侧推断，不从 assistant 文本猜 compact 状态。
- Workspace UI 入口是聊天里的 `/debug` slash command，生成 transient/local-only message；不新增独立页面，不写入 `messages_v2`，刷新后消失。

## Implementation Steps

1. 新增 backend context debug service，读取 workspace 文件、messages_v2、latest usage，输出按语义来源聚合的结构化 breakdown。
2. 新增只读 API：`GET /api/workspace/{workspace_id}/debug/context`，复用 workspace access 检查。
3. 新增 workspace chat `/debug` slash command，调用只读 API 并在当前 ChatPanel 追加 local-only system message。
4. 新增 CLI debug 命令：`investibook debug context [workspace-id]`，支持 table 和 JSON 输出。
5. 增加本地 contract 测试覆盖 enabled skills、evidence/issues、messages/tool payload、latest usage scaling。

## Verification Checklist

- Backend unit tests pass for context debug report.
- CLI package builds.
- Debug API does not mutate DB/files/session.
- `/debug` chat command does not call `appendMessagesToAPI`; command echo and result are local-only.
- `.opencode/.all-skills` 不计入 enabled skill context。
- 输出中同时保留 raw estimated tokens 和按最新 actual context_used 缩放后的语义来源占比。
- Example 输出不直接暴露 `messages_v2/.../parts/N` 作为主标签；主标签必须是语义项，detail/source_ref 才允许保留内部定位。
- Tool payload 不作为一级分类；必须根据路径/metadata 归到 Evidence、Skills & Knowledge、Cluster & Alert Metadata、Issue/source files 或 Unknown tool payload。