本项目以 apps/ 作为完整工作区。先从仓库根目录进入该目录，再准备配置：
cd apps
cp config/config.example.toml config/config.toml编辑 config/config.toml，填写模型服务信息：
[model]
provider = "openai" # 可选，省略时使用 OpenAI 兼容协议
api_key = "你的 API Key"
base_url = "https://api.deepseek.com/v1"
name = "deepseek-chat"api_key、base_url 和 name 必填。provider 选择调用协议，当前仅支持 "openai"，省略或留空时使用同一协议。其他兼容 OpenAI Chat Completions 的服务可填写对应的地址、密钥和模型名；专用协议需要新增适配器。
配置优先从启动目录的 config/config.toml 读取，只有文件名确实不存在时才兼容旧路径 apps/config/config.toml。首选文件不可读、是目录、符号链接断开、解析失败或缺少必填字段时直接报错，不回退。其他项目也在各自工作区内准备配置；不读取父目录配置。
主对话和轮数上限后的总结自动使用 SSE 流式响应，模型服务需要支持 OpenAI 兼容的流式 Chat Completions。无需配置流式参数，也不提供关闭开关；上下文摘要使用独立的非流式请求。这三类运行时请求的输出上限固定为 8,192 token，不提供配置项。
当前没有思考强度配置项，MiniCode 不发送 reasoning_effort，由模型服务或网关使用默认设置。gpt-5.6-sol 的官方默认档位为 medium（中等），中转网关可能覆盖它；实际档位以网关设置为准。此默认值来自 OpenAI 官方模型说明，不是 MiniCode 显式指定的参数。
在需要操作的项目目录运行。本项目沿用上一步的 apps/ 工作区；已安装到 PATH 时执行：
minicode未安装到 PATH 时，在 apps/ 内运行 ../bin/minicode；开发时可运行 go run ./cmd/minicode。工作区始终是启动目录，不会因为配置使用旧路径而自动切换目录。
也可以直接在命令行中提交任务：
minicode "分析这个项目"交互模式中可连续输入任务。使用 /exit、/quit 或 EOF 退出。
当标准输入和标准输出都连接终端时，MiniCode 进入全屏会话界面，只绘制本次运行的会话内容。上方显示回复、工具状态、审批、统计和错误，底部固定输入区；整个会话共用一个备用屏幕。
模型文本边生成边渲染 Markdown，标题、列表、加粗和代码块在生成过程中即可显示排版。后续增量按 50 毫秒间隔合并刷新，未闭合格式随新内容重新排版，渲染失败时回退原文。生成时自动跟随末尾，窗口大小变化时重新排版。完整回复仍显示在会话区；普通任务错误或超时后可继续输入，退出或 Ctrl+C 时恢复原终端屏幕和模式。
等待输入或工具审批时，可以滚动上方消息，底部输入区和已有草稿保持在原位：
| 操作 | 效果 |
|---|---|
| 滚轮 / 触控板上下滑动 | 上下查看会话消息，每个垂直滚动事件移动 3 行 |
PageUp / PageDown |
按消息区高度翻页 |
↑ / ↓ |
在当前输入的显示行之间移动光标 |
Shift+Enter / Ctrl+J |
在输入中插入换行 |
Enter |
提交整段任务输入或审批答案 |
/exit、/quit 或 EOF |
等待任务输入时退出会话并恢复原终端 |
Ctrl+C |
中断并退出，同时取消模型请求或工具执行 |
滚动和鼠标点击不会作为文字插入草稿，也不会提交任务或批准工具。鼠标模式只在读取输入时开启；模型生成回答和工具执行期间，输入区继续显示，滚动功能尚未接入。窗口缩放会重新排版，多行输入过长时只显示光标附近的部分。
模型请求工具时，程序先收齐工具名称与参数，并等待响应完整结束和校验通过，再按下节规则审批和执行。提前断线会报告错误，不执行该次回复中的工具，也不保存半截模型回复；已完成的历史步骤仍保留。
输出到管道或文件时不展示增量预览，完整回复保留 Markdown 原文；会话 ID、任务统计和错误写到标准错误。例如：
minicode "分析这个项目" >answer.md 2>run.log执行副作用工具时，审批说明和参数仍会写到标准输出；--yes 只跳过用户确认。工具原始结果回传模型并记录在会话中。流正常结束后，返回的 usage 会计入任务统计；服务未提供用量时显示 Token 不可用，只有部分响应提供时显示 （部分统计）。
默认情况下，MiniCode 在执行 bash、write 和 edit 等有副作用的工具前会请求确认。
使用 --yes 可以自动批准这些工具调用：
minicode --yes "运行测试并修复问题"--yes 会允许模型执行命令和修改文件，请只在可信项目和明确任务中使用。
未指定 --session 时，MiniCode 会创建一个新会话，生成标准小写 UUID，并自动保存对话、模型回复、工具调用和工具结果。无需为保存新会话传入额外参数：
minicode "分析项目结构"启动后会输出会话 ID：
[会话] 550e8400-e29b-41d4-a716-446655440000
记下该 ID。下次在创建它的同一个工作区中，通过 --session <id> 继续会话：
minicode --session 550e8400-e29b-41d4-a716-446655440000恢复后与正常启动一样等待输入，你可以直接输入下一项任务，无需在命令后附加“继续刚才的任务”。也可以像新会话一样，通过位置参数直接提交具体任务。
会话存档固定保存在当前工作区的 .minicode/sessions/<id>.json。--session 接收 UUID，不接收文件路径，也不会用指定 ID 创建新会话；ID 非法或存档不存在时程序会报错退出。
恢复时会加载已完成的消息历史、重新生成系统 Prompt，并读取当前工作区的最新 MiniCode.md；不会恢复运行中的进程、审批状态或文件读取缓存。本项目从 apps/ 启动后，存档位于 apps/.minicode/sessions/；原仓库根目录的 Session 不会因记忆迁移而自动搬迁，继续它们需要在原工作区恢复。Session 文件可能包含源码、命令输出和其他敏感内容，请勿提交到 Git；仓库已忽略根目录与 apps/ 下的 .minicode/。
在输入循环中执行 /compact，可以主动压缩当前会话：
> /compact
已完成上下文压缩，保留最近约 20000 token 的原始消息。
近期消息不足以留下可压缩旧内容时，程序提示“当前没有需要压缩的旧消息”，并跳过模型调用。命令本身不进入对话历史，当前不支持在 /compact 后附加摘要指令。
程序也会在每次正常模型请求前自动检查预算，包含新用户输入、项目记忆及其包装、已有历史和工具声明。工具执行期间，等待整批结果完成后再检查下一次请求。当前固定以 262,144 token 为窗口，剩余空间严格小于 16,384 token 时触发压缩；这些预算均不可配置。
压缩从最新消息向前选取接近 20,000 token 的近期原文，工具调用和全部结果整体保留。最新一条消息或工具批次很大时，实际保留量可能超过 20k。更早内容使用当前模型和 pi 的摘要 Prompt 生成目标、约束、进度、关键决策、下一步和必要上下文；后续压缩会更新已有摘要。
摘要输入不额外截断。完整输入能放进摘要请求窗口就一次发送，否则按 UTF-8 边界分块，各块依次更新摘要。工具执行阶段原有的输出大小限制仍然生效；摘要流程保留历史里已经收到的全部文本。
摘要完整成功且候选上下文校验通过后，程序更新独立压缩检查点。模型读取“系统 Prompt → 项目记忆（如有）→ 新摘要 → 近期原文”；独立注入的记忆块不进入摘要输入，完整原始历史继续保留在内存和 Session v2 存档中。手动压缩立即保存到现有会话文件，自动压缩和超限恢复在本轮结束时保存。恢复会话时读取原始历史、检查点和最新项目记忆，再构造模型上下文。v1 存档可迁移，旧版已经丢弃的原文无法恢复。
摘要失败、为空、返回工具调用、被输出长度限制截断、校验失败或被取消时，保留旧检查点和原始历史。摘要请求的调用次数和模型返回的 token usage 计入统计；文件修改和测试状态由 LLM 归纳进摘要，需要精确信息时应重新读取文件或验证。
每次模型请求发送前都会严格检查消息结构与工具调用结果配对。缺少或重复工具结果、结果没有对应调用、同批次调用 ID 重复、参数 JSON 不完整等情况会在本地报错并停止该次请求。三次连续压缩的语义验收是开发测试，普通任务无需额外配置；测试启用方式及当前验收状态见 规格说明。
模型明确提示上下文超限时，程序调用同一压缩函数，仅重试当前正常请求一次，不重复执行已完成的工具。窗口大小是代码假设，程序未自动识别所用模型的实际限制；最新输入或工具批次本身过大时，压缩旧历史仍可能失败。
每轮任务默认最多运行 1 小时，包含模型请求、工具执行、上下文摘要和最终总结；手动 /compact 也使用这个超时。可以通过 --timeout 调整：
minicode --timeout 30m "运行完整测试"常用时间格式：
30s 30 秒
10m 10 分钟
1h 1 小时
自动批准工具并设置超时（新会话仍会自动保存）：
minicode --yes --timeout 30m "检查项目并修复测试"记下启动时显示的会话 ID，之后继续该会话：
minicode --yes --session 550e8400-e29b-41d4-a716-446655440000minicode -h工作区根目录的 MiniCode.md 常驻保存关键约定、常用命令和按需详情目录。可以直接用编辑器维护这个 UTF-8 文件；新会话自动读取，不需要 --session。只读取启动目录根部的文件，不扫描父目录，也不会自动寻找子目录的记忆。本项目入口是 apps/MiniCode.md，需要从 apps/ 启动。
文件不存在时按无项目记忆处理，程序不会自动创建；已有空文件也不注入。临时任务进度保留在 Session 中，项目记忆只保存稳定、可复用的知识。
启动后明确说明要保存、更新或删除什么，例如依次输入：
> 记住：本项目使用 go test ./... 运行测试。
> 查看当前 MiniCode.md 中的项目记忆。
> 更新项目记忆：默认测试命令改为 go test -race ./...。
> 把会话恢复的设计结论保存为按需记忆，并更新目录。
> 忘记项目记忆中的默认测试命令，保留其他内容。
> 清空全部项目记忆。
这些是普通对话请求，模型会通过现有文件工具执行。按用户约定，记忆查询和维护不提供 /memory、/forget 专用命令。read 可直接读取，write 和 edit 沿用执行前审批；拒绝时文件不变，--yes 自动批准。
系统 Prompt 要求模型先读完整内容、保留其他约定、避免重复记录，并用新约定替换冲突内容。文件不存在时可用 write 创建，更新或删除指定内容使用 edit。普通任务完成或测试通过不触发自动保存；这些维护规则依靠模型遵循提示，保存结果可以通过查看文件确认。
较长的专题知识放在 .minicode/memory/<topic>.md，MiniCode.md 只保留关键约定和名称、适用场景、相对路径组成的目录。例如：
## 常驻约定
使用 Go，修改后运行测试。
## 按需目录
- [会话恢复](.minicode/memory/session-compaction.md)：修改 Session 保存或恢复时参考。
- [终端交互](.minicode/memory/terminal.md)：修改全屏输入或消息滚动时参考。用户要求“修复会话恢复问题”时，模型先看到常驻约定和目录，再根据场景调用 read 读取 session-compaction.md。正文作为普通工具结果进入上下文，终端资料无需由宿主预读。模型负责选择专题，程序不做关键词检索、向量召回或自动扫描；没有相关目录的普通任务可以不读取详情。
本地工作区已建立代码组织、会话与上下文压缩、项目记忆、终端交互四个专题，详情位于 apps/.minicode/memory/。该目录被 Git 忽略，详情不随仓库共享；目录目标缺失、不可读或过时时应核对当前代码，不能只凭名称猜测内容。
维护一个专题时，模型按以下顺序操作：
- 读取根目录记忆和相关详情，检查重复、冲突并保留其他内容。
- 先成功写入或更新详情，再更新
MiniCode.md中的目录项；关键约束继续保留在常驻部分。 - 忘记整个专题时先清空详情，再移除目录项；清空全部记忆时先清空目录列出的详情，再清空根文件，保留空文件。
目录选择和同步依赖模型遵循提示，两份文件分别原子写入，并不是一个多文件事务；拒绝审批或任何一步失败时，模型应如实报告已完成的部分。本地测试已验证工具流程；2026-10-18 按用户决定跳过真实模型对专题选择、去重、冲突更新及删除的验收，Day 15 已收尾，跳过项未执行。
常驻文件 MiniCode.md 的正文和目录合计必须满足：
- 合法 UTF-8，不含 NUL 字符；
- 最多 64 KiB；
- 原文最多 4,096 个本地估算 token。
粗估方式是 ASCII 字符数除以 4 向上取整，每个非 ASCII 字符按 2 token 计算，实际模型分词可能不同。正文与参考消息的包装还会计入完整模型请求预算。预算固定在代码中，超限时不会截断文件。
通过 write 或 edit 修改根目录 MiniCode.md 时，完整候选文件会在写入前校验。失败作为工具错误回传，原文件保持不变，模型可以缩减内容或修正后重试。直接用编辑器修改后，若文件不可读、编码无效或超限，启动或下一次任务会报错；修正文件后再重试。
详情目录下的 Markdown 文件同样要求 UTF-8、不含 NUL、最多 64 KiB，不套用常驻 4,096 token 预算。read、write 和 edit 检查完整详情内容；读工具沿用默认 200 行和 64 KiB 输出上限，出现截断标记时按 offset / limit 继续读取。未选择的损坏或缺失详情不会阻断会话启动，显式读取时错误作为工具结果回传。
新建和恢复 Session 时、每个用户轮次开始前、手动 /compact 前会重新读取文件。模型成功通过 write / edit 修改根目录记忆后，程序在整批工具完成时刷新，下一次模型请求使用新内容。用编辑器或 shell 在任务执行过程中修改时，下个用户轮次或手动压缩前会读取最新内容。
当前整个文件常驻模型上下文，顺序为“系统 Prompt → 项目记忆（如有）→ 摘要（如有）→ 近期原文”。记忆作为参考信息使用，系统规则和本次用户明确要求优先；文件中的命令与结论仍需结合当前项目检查。
自动注入的常驻项目记忆独立于原始对话和压缩检查点，连续压缩后仍从当前文件构造。通过 read 读取的详情进入当前会话历史并参与普通压缩，需要精确信息时重新读取当前文件；新会话仍只先加载常驻约定和目录。清空后保留空文件，后续不再注入记忆块；旧 Session 中的用户消息、工具记录和摘要仍保留，因此清空项目记忆不会清除会话历史。系统 Prompt 要求删除后未经用户重新授权不从旧历史写回。
只有把详情正文放入独立文件，才能减少初始注入量；在 MiniCode.md 中单纯标注“常驻”和“选择性”，整个文件仍会注入。实现与阶段收尾记录见 Day 15 开发计划。