从零开始，把 KODER
变成适合你的工作工具

先知道你要得到什么

目标是一个能按你的规范工作、对你的领域有资料依据、逐步适应你表达习惯的工具。

本教程面向完全没用过终端的人，也保留进阶用户需要的命令和配置。你不必先学编程。先完成本地角色、资料和检查，再决定是否连接真实模型。

三种入口共用同一份数据目录、角色与空间。TUI 启动时也会启动这套本地后台，并显示它的网址。你可以在网页编辑长材料，然后回到终端工作。后台不是云服务器；关闭启动它的程序后，相应网址会停止响应，已经保存的数据仍在。

当前版本提供 CLI、TUI、本地配置后台、资料投喂、输出检查与有边界的学习。真实模型请求需要你明确选择模型端点、在本机提供凭据，并完成本产品 GitHub 激活。下载和各平台实测结果请核对发行页的验证记录；配置保存、健康检查和演示文字都不等于真实请求已经通过。

任何岗位都可以先定义自己的角色和资料。选择“教师”“工程师”等名字只建立工作边界，不会自动得到该专业的全部知识。专业适用性取决于你提供的可靠资料、代表性案例和实际验证。

按你的起点选择路线

每一段都有一个能看见的完成结果，不必一次学完所有命令。

第一次练习的最短闭环

1. 安装或使用团队提供的当前本地包；运行 koder-open version 确认版本。
2. 在独立数据目录启动 setup 或 tui。
3. 把助手名字、工作目标、话题范围和语言改成自己的。
4. 导入 my-standard.md，检查内容后启用，并添加输出检查。
5. 检查 bad-answer.txt：应拦截；检查 good-answer.txt：应通过机械检查。
6. 添加一个真实遇到的问题和一张复习卡；先做本地练习，再确认结果。

做到这里，你已经掌握定制的主体。模型调用、身份授权和自动选择学习活动放在后面的章节完成。不要用演示用的三个任务 ID 冒充自己的三次真实经验。

第一次接触时会遇到的词

把不同概念分开，配置会简单很多。

从哪里下载、选哪一个包

先核对平台和版本，再核对文件；不要从旧教程猜下载命令。

本教程对应页首所示版本。到下方本版发行页下载与你设备匹配的程序包及同名 .sha256 文件；如果该版尚无附件，等待团队发布，不要使用旧包代替。Mac 文件是 koder-open-0.2.0-dev.7-darwin-arm64.tar.gz，Windows 文件是 koder-open-0.2.0-dev.7-win32-x64.zip。两端都包含本产品真实授权配置。

打开本版发行页、程序包与校验文件离线手册不内含 CLI 程序包；请使用会话中的包文件或联系团队。

团队入口：karmenloop.com；支持邮箱 info@karmenloop.com。请以本版发行页的附件为准。不要把旧版公开下载脚本得到的旧版本当作这份教程中的完整功能。

当前包的 SHA-256：以同一发行版附带的 .sha256 文件为准；不要使用旧候选摘要。校验值只能检查文件是否一致；应从你信任的发布方渠道取得原始包和摘要。不要为了运行未确认的包关闭系统安全保护。

Mac：从打开终端到启动工具

这条路线针对 Apple Silicon Mac。原生包已经带运行时，普通用户不需要另外安装 Node.js。

1. 在“关于本机”确认芯片为 Apple M 系列。按 Command + 空格，输入 Terminal 或“终端”，打开。
2. 把包放进“下载”，用访达双击解压。得到一个以 koder-open-0.2.0-dev.7-darwin-arm64 命名的文件夹。
3. 在终端输入下面的校验命令；如果你改过下载位置，替换路径。摘要应与上一章相同。

shasum -a 256 "$HOME/Downloads/koder-open-0.2.0-dev.7-darwin-arm64.tar.gz"

进入解压后的文件夹。路径不同，就在终端输入 cd （末尾一个空格），把该文件夹从访达拖进终端，再按 Enter；拖入文件夹只填写路径。

cd "$HOME/Downloads/koder-open-0.2.0-dev.7-darwin-arm64"
sh install.sh

安装器会先验证包内文件、展示四份条款，并要求明确接受。只有你阅读后同意，才按屏幕提示输入 accept；不同意就停止。教程不会替你同意。安装条款同意与之后的 GitHub 运行授权是两道不同的门。

当前包为临时签名、未做 Apple 公证的开发包。若系统阻止运行，保留提示并联系团队获取经过确认的分发；本教程不要求关闭 Gatekeeper、删除隔离属性或绕过系统警告。

export PATH="$HOME/.local/bin:$PATH"
koder-open version --json
koder-open setup --home "$HOME/KoderLearningData" --port 0

第一行只影响当前终端窗口，关闭后可重新执行；需要长期 PATH 设置时按自己的 shell 管理习惯配置。version 应显示 0.2.0-dev.7。setup 会输出一个 http://127.0.0.1:端口 地址，复制进浏览器。端口每次可能不同，以终端打印值为准，不要一直用某个旧的预览地址。

若命令仍找不到，可用完整路径启动：

"$HOME/.local/bin/koder-open" tui --home "$HOME/KoderLearningData"

Windows：准备与安装路线

Windows x64 已在原生 CI 验证下载、安装、CLI、本地学习和 ConPTY TUI。本轮包仍是待发布方授权服务就绪的开发草稿，不等于已经完成正式激活。

取得团队正式确认的 win32-x64 或 win32-arm64 ZIP 后，再按此路线进行。ARM 与 x64 不要互换；不要使用 Mac 的 darwin-arm64 文件。

1. 在开始菜单搜索 PowerShell，使用普通用户窗口。
2. 右键 ZIP，解压全部到本地普通目录，例如 C:\KoderOpen。
3. 进入解压目录：输入 cd ，再填实际文件夹路径；含空格的路径用英文引号。
4. 先对照团队提供的 SHA-256，再运行该目录内的安装器。

Get-FileHash -Algorithm SHA256 -LiteralPath "$HOME\Downloads\你的Windows包.zip"
Set-Location -LiteralPath "C:\KoderOpen\实际解压目录"
.\install.ps1

安装器应展示条款并询问接受，普通安装不需要管理员权限。默认命令在 %LOCALAPPDATA%\KarmenLoop\koder-open\bin\koder-open.cmd。可从 PowerShell 直接调用：

& "$env:LOCALAPPDATA\KarmenLoop\koder-open\bin\koder-open.cmd" version --json
& "$env:LOCALAPPDATA\KarmenLoop\koder-open\bin\koder-open.cmd" tui --home "$HOME\KoderLearningData"

安装器也可通过团队提供的 koder-open.ps1 下载入口使用；该入口校验 ZIP 摘要与精确文件清单后才进入条款确认。推荐先下载、解压并校验发行页附件，运行包内 install.ps1；只有发行页已提供对应附件时，下载入口才可用。

若提示脚本被策略阻止，先记录错误并联系系统管理员或团队获取符合本机策略的分发方式。不要把 Set-ExecutionPolicy Unrestricted、整机 Bypass 或管理员权限当作教程必做步骤。Microsoft 对执行策略的说明见官方文档。

得到已验证的 Windows 包后，应实际检查：中文/空格路径、终端中文、保存重开、安装升级、模型授权和退出恢复。Mac 上的测试不能替代这些结果。涉及 JSON 参数的 Windows 进阶操作优先使用本教程的 JSON 文件和网页表单，避免不同 PowerShell 版本的原生命令引号差异。

TUI：直接在终端里使用

不想在网页里操作时，用这个入口。菜单是真实功能，数据仍交给同一套本地后台。

koder-open tui --home "$HOME/KoderLearningData"

Windows 使用上一章的完整 koder-open.cmd 路径，数据路径改为 $HOME\KoderLearningData。下面的界面项目与两端保持同一套实现；Windows x64 已验证原生 ConPTY 菜单、中文角色保存与重开；仍需在你的实际终端确认显示与键位。

Koder Open CLI · Terminal UI
Version 0.2.0-dev.7 · default / assistant

> Role settings: purpose, scope and tone
  Feed skills and check outputs
  Learning cycle
  Model and GitHub license
  Run an authorized text task
  Switch role or space
  Inspect saved state
  Help and local backend URL
  Save and exit

1. 进入 Role settings，按提示填名字、目标、话题、语气、语言；填完整个表单才保存。
2. 进入 Feed skills and check outputs → Import，填本地文本文件路径、Skill ID、必需短语和禁用短语。导入后先 disabled。
3. 重新进入该 Skill 查看内容，再选 Enable reviewed skill。
4. 用 Check a sample answer file 测试本地样例。
5. 进入 Learning cycle 配置范围、投喂问题、添加复习卡、练习、复核结果。
6. Help and local backend URL 会显示网页后台地址，适合切去编辑长文本或完整 JSON。

输入文件路径时使用实际路径，建议不带外层引号，例如 /Users/你的名字/Documents/my-standard.md；这里是表单，不是 shell 命令。TUI 一次输入一行，长文档在文本编辑器保存成 UTF-8 后导入最方便。

本地后台：长资料和完整设置放在这里

你可以只用按钮完成大部分定制，不必手写 JSON。

koder-open setup --home "$HOME/KoderLearningData" --port 0

角色页面修改后点击 Save settings。保存后右侧 Saved configuration 的版本会变化。没有点保存的字段只是草稿；网页演示检查使用已保存值。重开同一目录和角色，确认名字仍在，才证明持久保存。

网页上的 Current role 是角色 ID。它与终端的 --role 对应；setup --role 某ID 不会自动替网页切换角色，网页仍需填 Current role 并点击 Open。网页目前没有单独的空间切换控件；需要特定 --space 的管理用 TUI 或 CLI。

如果你同时用多个窗口修改同一角色，后提交的一方可能看到版本冲突。先复制未保存的草稿，再重新打开、核对差异和保存，避免覆盖别人刚保存的规范。

把通用起点变成你的角色

先定义工作合同，再讨论“像不像我”。名字、范围、方法和调性需要一起明确。

可直接下载 role-config.json。初学者先用普通表单；进阶时到 Full configuration，确认当前角色 ID 是 assistant，再复制文件全部内容进去保存。若当前角色不是 assistant，要把 JSON 的 id 改成当前角色 ID，不能用粘贴配置强改被锁定的角色身份。

不要在 knowledge.sourceRefs 填一个硬盘路径，就以为文件已经读进来了。该字段只是资料引用。当前可实际进入文本请求的资料，是你已经导入、审阅并启用的 Skill 文本；网页、PDF、Word 等需先由你转成合适的文本。

领域理解也要有方法

以“发动机是什么原理”为例，你可以要求回答覆盖：系统目的、组成部分、每部分作用、输入与输出、能量如何转化、关键因果关系、成立条件、常见误解、如何验证。但具体机型与技术结论仍应依据你提供的可靠材料，不靠一个角色名字自动补齐。

投喂之前：把资料整理成能用的结构

少量可靠、边界清楚的材料，通常比一口气塞入杂乱资料更容易检查。

1. 先写一份 1–3 页的核心规范，下载 my-standard.md 改成自己的内容。
2. 再按岗位建立少量主题文件，例如“术语表”“流程与例外”“通过验收的案例”。同一个导入文件不要超过 128 KiB。
3. 每份资料注明适用范围、来源、日期、版本；纠正旧规范时明确指出替代哪一条。
4. 确认你有权把资料交给本地工具和你选定的模型服务。需要保密的部分先做脱敏或不提供。
5. 一次只新增一类规范，测一组真实案例，保留有效结果后再扩充。

Markdown 的 # 是标题标记，不会变成可执行代码。当前导入只复制文字，不安装依赖，不自动访问链接，不读取同文件夹其他文件，也不执行 Skill 里面的脚本。“喂资料”是建立可追溯的上下文与检查规则，不是训练基础模型权重。

真正投喂：导入、审阅、启用、重测

这四步少一步，结果都会不同。

网页操作

1. 打开 Skills & output rules。
2. 选择 Skill file，或在 Instructions 粘贴文字。
3. Skill ID 填 my-standard；它是内部标识，不是中文显示名。
4. 展开 Add enforceable output checks，先设置 Required phrases：依据：；Forbidden phrases：保证结果 和 已经替你发送。Maximum characters 可填 1200。
5. 点击 Import disabled skill。
6. 在 This role’s skills 展开内容和检查，确认无误，再点击 Enable。
7. 用好坏样例重新测。改写同一 Skill 后，替换版会重新 disabled，需要再审阅和启用。

TUI 操作

Feed skills and check outputs → Import a Markdown / text file → 填路径、ID 和检查。再进入同名 Skill → Review → Enable reviewed skill。长段落请在文件里编辑；TUI 的短语输入用逗号分隔，含逗号的精确短语可在网页设置。

Mac CLI 操作

koder-open skill import ./examples/my-standard.md --id my-standard --rules '{"requiredText":["依据："],"forbiddenText":["保证结果","已经替你发送"],"maxCharacters":1200,"format":"text"}' --home "$HOME/KoderLearningData"
koder-open skill list --home "$HOME/KoderLearningData"
koder-open skill enable my-standard --home "$HOME/KoderLearningData"

CLI 列表会显示导入的 Skill、摘要和 enabled 状态，默认不把整段文字全部打印出来。启用只增加内容指导与机械检查，不会授予 shell、文件读写、发消息或商业授权。你自己的规范若与其他启用资料冲突，应先解决冲突，不要靠反复重试期待模型每次猜对。

试一下过滤筛：好坏答案都要测

你要确认它既能拦住违规输出，也允许符合规范的内容通过。

到网页 Try the output filter，把 bad-answer.txt 的内容粘进去，点击 Check sample；它应该显示 Withheld。再使用 good-answer.txt，应显示配置的机械检查通过。TUI 的 Check a sample answer file 可直接选这两个文件。

koder-open skill check ./examples/bad-answer.txt --home "$HOME/KoderLearningData"
koder-open skill check ./examples/good-answer.txt --home "$HOME/KoderLearningData"

第一条预期退出码是 3，第二条是 0；错误码非零在坏样例里是正确结果。如果所有东西都通过，检查规则是否为空、Skill 是否启用、数据目录/角色/空间是否相同。如果所有东西都拦住，检查必需短语是否互相矛盾、是否强制了输出无法满足的格式。

接入模型：协议、地址、名字和 Key

当前真实请求还受发布方授权服务门控；先把配置理解清楚，不要盲目反复调用。

到 Model connection 选择一个起点，再根据你的模型服务账号填写。预设只是填表，不证明账号有权限、额度够用或参数完全兼容。你可以用官方 API、获准的网关或本机兼容服务；模型输出仍要经过同一套角色与检查。

先在启动程序的终端设置 Key

Mac 的以下方式不把 Key 直接写进命令历史。执行第一行后粘贴自己的 Key 并按 Enter，输入不会显示；它仍会作为该终端启动进程的环境变量存在。

read -r -s KODER_OPEN_MODEL_KEY
printf '\n'
export KODER_OPEN_MODEL_KEY
koder-open tui --home "$HOME/KoderLearningData"

网页/TUI 的 Credential variable 都填 KODER_OPEN_MODEL_KEY。如果页面选的是某个预设自己的变量名，就在启动环境里使用同一个名称；不要只设置 A，却让程序读取 B。修改后需要在带新环境变量的终端重新启动对应后台。已启动的旧后台不会自动获得另一个终端的新变量。

$koderSecure = Read-Host "模型 API Key（输入不回显）" -AsSecureString
$env:KODER_OPEN_MODEL_KEY = [System.Net.NetworkCredential]::new("", $koderSecure).Password
Remove-Variable koderSecure
& "$env:LOCALAPPDATA\KarmenLoop\koder-open\bin\koder-open.cmd" tui --home "$HOME\KoderLearningData"

保存模型配置后，只能说“配置已保存”。发布方服务就绪并完成授权后，明确勾选这次数据发送，再发一个很小的测试任务。看到完整回答、过滤检查和预期内容，才是这次请求成功。失败时看错误码；不要把 Key 改填到 Skill 或安装条款摘要里。

DeepSeek 短文本与思考模式

DeepSeek 当前默认启用思考。短任务可在 CLI 的 model configure 命令追加 --thinking disabled，网页选择 Thinking mode → disabled，TUI 配置模型时选择 Disable thinking。其他供应商保持 default，只有端点明确支持这个字段才启用。输出上限同时约束推理和正文；MODEL_OUTPUT_INCOMPLETE 表示答案被截断或未完成，程序会拦截，不能当成功。提高额度前先检查任务长度与思考设置。

字段依据：DeepSeek 官方思考模式文档。配置只控制已公开的接口参数；不会显示或保存模型内部推理。

不同运行方式的边界

• 原生 CLI 包含运行时，普通使用不需要 Node。若团队另行授权提供源码，源码运行要求 Node 22 或以上；从 Node 官方下载页选择适合系统的受支持版本，并用 node --version核对。本轮实际验证使用 Node 22.23.2。
• 远程模型需要网络；本地编辑和样例检查可以离线。真正的离线 AI 还需要你已安装、已启动的本地模型服务，本工具不会自动提供模型权重。
• 某些 Coding Plan / 订阅计划限制用途。当前通用角色 host 会拒绝已识别的不适用订阅端点；使用服务商允许的 API 产品。不要把“支持协议”理解成“已验过全网所有模型”。
• 本地无凭据模式只允许明确的 loopback 地址；云端必须使用 HTTPS。这里不支持静默换供应商、自动搬运 Key 或自动跨主机重试。

条款、GitHub 与使用授权

这是身份和产品授权，不是模型 Key，也不是让你把资料传进 GitHub。

当前使用的是个人非商业授权：自己的角色设置和 Skills 可以编辑；商业使用、产品代码修改及二次开发需要团队另行书面授权。岗位和行业案例是定制方法示范，不自动授予组织生产或商业部署许可。这里的 Open 是产品名；按当前限制性条款，不能称为允许自由修改和商用的标准开源许可。

1. 打开 License & team。阅读 terms、privacy、disclaimer、licensing 四份完整文件及其版本。
2. 只有理解并同意，才分别勾选四份文件。不同意可以退出，仍可查看本地配置和说明。
3. 发布方配置完成后，点击 GitHub 设备授权入口，会显示一个验证码和 GitHub 验证网址。
4. 在你自己打开的 GitHub 页面登录，核对应用与权限，输入这次设备码，确认后回到工具检查授权状态。
5. 状态应成为 authorized，并保存可验证的签名授权；勾选框、一个设备码或本地 JSON 文件都不等于已经获授许可。

短期授权最长 24 小时，接近到期时会在固定 30 天窗口内尝试续租；到固定期限、版本/条款变化或撤销后需重新授权。网络中断时只可用已经有效且未到期的授权，不能无限离线延期。退出本机授权不会删除服务端历史条款回执。设备流程通用原理见 GitHub 官方说明；本工具自己的授权期限由当前签名协议决定。

GitHub Star 和推荐链接是自愿项，与是否发许可证无关。商业授权、隐私或回执问题联系 info@karmenloop.com；不要在邮件里附 Key、token 或客户资料。

发出第一条真正的任务

先小范围证明有用，再增加难度和资料。服务未就绪时跳过真实调用，不用假回答代替。

确认角色已保存、Skill 已启用、模型配置和环境变量对应、授权状态有效。网页到 Model connection 的 Try an authorized text request；TUI 到 Run an authorized text task；CLI 使用 run。每次模型请求可能收费。

目标：把下面的流程说明改写成一段给新同事看的入门解释。
范围：只使用我启用的规范和下方事实，不补造制度。
事实：流程分为登记、核对、交接三个步骤；每步都需记录处理人。
输出：先一句话说目的，再说明步骤与检查点，结尾写依据。
缺资料时：指出缺口，不要假设已经完成交接。

koder-open run '把登记、核对、交接三个步骤写成新同事入门说明，标明需要确认的地方和依据。' --home "$HOME/KoderLearningData"

收到结果后检查四件事：用的是不是当前角色；有没有遵守必需/禁用短语和格式；资料之外是否编造了事实；表达是不是你愿意使用的样子。不要因为“有文字返回”就直接用于专业场景。

run --demo 只是配置演示，不调用模型，也不执行真实任务。task、eval、deploy 等接线尚未完成；当前文本 host 不会真的发邮件、操作电脑、部署服务或替你执行渠道工作。

让它逐步符合你的调性

风格从具体偏好和反复验证中建立，不靠一句“懂我”。

先选一个可判断的表达方向

1. Role settings 中先调语言、语气、长度和结论优先。不要一次混入互相矛盾的要求，例如“每次最多一句话”又“每次给十步完整推导”。
2. 在 Skill 添加两到三个你的正例，以及反例和修改原因。使用你有权提供的文本。
3. 用相同任务重测，看输出是否更贴合。若只有自然语言要求不稳定，补上能机械检查的格式规则。
4. Behavior & preferences 中的显式纠正表单可保存建议；点击 Apply 才写成角色配置。建议本身不会自动生效。
5. 记下保存前后的版本。改变风格会让受影响的学习成果失效，需要重新验证。

koder-open learn suggest /voice/detail brief --evidence '我希望先给结论，常规回答更简短；必要时再展开。' --home "$HOME/KoderLearningData"
koder-open learn list --home "$HOME/KoderLearningData"
koder-open learn apply 实际建议ID --home "$HOME/KoderLearningData"

可建议的字段限于 voice：tone、detail、locale、document、conclusionFirst。它不是让模型任意修改工具和权限的入口。忘记一条建议只删除建议记录，已经应用的配置需自行编辑或回滚；两者不要混为一谈。

开启学习前，先画好边界

先规定“学什么、用什么、什么时候用”，再让系统安排预习和复习。

1. 到 Role settings 填好允许话题，例如工作写作、个人学习，并保存。
2. 启用准备作为学习资料的 my-standard Skill。
3. 到 Learning cycle → Choose learning scope and limits。
4. 勾选 Enable learning for this role and space；从已保存的角色话题中选学习话题，从已启用的 Skills 中选批准材料。
5. 初期每天模型学习调用先设 1，保留 30 天；这只是学习活动限额，不是总账号预算。
6. 先保留两个额外选项关闭：接受后的学习笔记参与回答、保存显式标记的任务输入。熟悉后再逐项打开。
7. 点击 Save learning boundary；先看本地计划和练习，不必马上发模型。

TUI 的 Learning cycle → Choose learning boundary and sources 会按顺序问同样的范围、材料、复用、捕获、预算和保留期。空白 Enter 保留原值；若要清空已选项，使用网页或对应 JSON 文件明确修改。

教程样例 learning-policy.json 默认开启按需学习，但关闭笔记复用与任务捕获。它要求角色已经包含相同中文话题、my-standard 已启用。pause-learning.json 用来暂停。

koder-open learn configure ./examples/learning-policy.json --home "$HOME/KoderLearningData"
koder-open learn status --home "$HOME/KoderLearningData"

学习记录默认在本机；明确同意发模型时，所选端点会接收角色、已启用 Skill 和选定学习记录。当前没有整机活动监视、自动吞入所有聊天、后台定时学习或基础模型训练。最大 12 个话题、24 个学习源、100 条观察、24 张复习卡、40 条近期尝试；学习模型调用最多每天 4 次，还受当前角色更低的限制约束，按 UTC 日期计数。

预习：围绕反复问题和正在做的事情准备

预习的输出应能让下一次任务更容易完成，而不只是多一篇泛泛总结。

1. 在 Personal study plan 的 Add a problem or current task 中，选择话题和问题类型：Recurring question、Problem encountered、My correction 或 Current task。
2. 为同一真实任务使用相同 task ID；不同任务用不同 ID。写清实际遇到的困难、纠正或当前目标。
3. 如果已经知道下一步，就填 Expected next task；不知道可以留空。系统生成的下一步只会标为 hypothesis，等你确认。
4. 累计至少三个独立任务中的问题记录，才会显示 Repeated need。不要为了触发标签复制同一任务换三个 ID。
5. 读计划中的资料缺口、到期复习、当前任务与建议顺序，再选择学习活动。

教程中的 observation-1.json、observation-2.json、observation-3.json 和 current-task.json 全是演示记录。可以在独立练习目录体验，但用真实助手时要替换成真实且授权的事实。

koder-open learn observe ./examples/observation-1.json --home "$HOME/KoderLearningData"
koder-open learn observe ./examples/current-task.json --home "$HOME/KoderLearningData"
koder-open learn plan --home "$HOME/KoderLearningData"

到 Study and rehearse，选 Pre-study 或 Choose the next useful activity。好预习可以包含：任务目标、前置概念、系统组成与因果关系、关键依赖、资料缺口、一个小案例、自测题和如何检查。没有批准资料时，应先补资料，而不是要求模型自编“专业知识”。

koder-open learn study ./examples/activity-prestudy.json --share-learning --home "$HOME/KoderLearningData"

自动选择下一项时，系统优先处理未解决失败，其次到期复习，然后预习；已有本轮有效且被接受的预习成果后，才安排预演。一次点击至多一条模型请求，不会悄悄连跑一整晚。结果先进入待审草稿。

复习：让正确方法能再次用出来

复习卡要有资料依据、问题、认可的参考答案和可检查条件。

1. Spaced review → Add an approved review question。选择话题和批准的资料 Skill。
2. 写一个具体问题，再写你核对过的参考答案；参考答案也要通过当前角色和 Skill 的输出检查。
3. 设置答案必须包含的短语，例如“目标”“范围”“依据：”；不应设置与参考答案相冲突的条件。
4. 保存后，卡片立即到期。先不看参考答案，写自己的答案，点 Check my practice；或在明确批准模型数据发送后选 Model self-review。
5. 机械检查失败的内容会被拦截。机械检查通过后，去 Learning review queue 检查来源和意思；确实正确才 Accept reviewed learning，否则 Needs more study。

第一次被接受的到期复习后，间隔为 1 天；后续被接受的到期复习依次延长到 3、7、14 天。提前练习可以做，但不会提前增加复习阶段；失败或人工判定还需学习，会重置并回到补课。标准、范围或资料改变，也会要求重新验证。

koder-open learn card ./examples/review-card.json --home "$HOME/KoderLearningData"
koder-open learn status --home "$HOME/KoderLearningData"

把状态中的 cards[].id 复制到 practice-answer.json 的 cardId，再运行练习。返回的尝试 id 填入 grade-pass.json 或 grade-retry.json，最后再提交人工判断。大写 REPLACE_WITH_… 是占位符，不是可以直接运行的真实记录。

koder-open learn practice ./examples/practice-answer.json --home "$HOME/KoderLearningData"
koder-open learn grade ./examples/grade-pass.json --home "$HOME/KoderLearningData"

当前“到期”是重新打开工具时计算的待复习项，不代表已经设置了系统通知、定时任务或后台唤醒。模型自答通过格式检查，也不能自己宣布知识已掌握。

补课：从失败里找出具体缺口

“补课”应针对某个失败条件和相关资料，不应自动扩充权限或重写用户规则。

1. 先看失败来自哪里：缺必需短语、出现禁用词、JSON 错误、资料不足，还是你判断它理解错了。
2. Learning review queue 中，被拦截的尝试只保存失败码，避免把违规回答当成可复用知识。语义有问题但机械通过的回答，用 Needs more study 标记。
3. 在计划中查看未解决失败和资料缺口。补充或修订你批准的材料，再明确保存/启用。
4. 选 Remediation；它会收到相应批准材料、失败条件以及该话题的参考复习答案，形成纠错说明和练习草稿。
5. 复核纠错依据，再做相应练习。后续被接受的相同复习项可解决此前失败；普通话题失败则需要有效补课结果被接受。

可以使用 activity-remediate.json。例如“说明文遗漏目标与依据”，就补“如何确认任务目标、范围和来源”，再用一个新案例练习，不是泛泛要求“再聪明一点”。

失败或取消的模型学习尝试仍占当天次数；删除记录或忘记全部也不会清掉必要的当天计数。达到额度后，应等到下一 UTC 日，或在你的角色限制内明确调整设置。不要拿不断重装当成额度管理方式。

预演：提前准备下一步，仍然只做模拟

已知的下一任务和模型猜测的下一任务，需要清楚区分。

先把你确实打算做的下一步写进 Current task 的 Expected next task。若只是系统建议的“为下一步准备清单”，它是待确认假设，不是新的任务授权。确认准备目标后，选 Future-task rehearsal。

• 输入应包含：准备什么、允许用的资料、输出样式、预计困难和完成检查点。
• 输出应包含：步骤草稿、每步所需输入、风险/缺口、检查点、需要你决定的问题；规范允许时给一个样例。
• 预演不实际写客户文件、发消息、付款、变更配置或部署渠道，也不能把模拟结果写成真实完成。
• 你接受的是一个学习草稿或方法笔记，不是给它未来无限执行权。

koder-open learn study ./examples/activity-rehearse.json --share-learning --home "$HOME/KoderLearningData"

例如准备明天的培训，可以先预演“讲解顺序、最可能的误解、三个提问、如何检验学会”。如果材料缺乏，就先给缺口清单和补充路径，不宣称已掌握整个行业。

让被确认的学习成果参与日常回答

先确认成果有效，再单独开启复用；这一步是个性化的关键。

1. 至少有一条当前规范下经过你复核的 accepted 学习结果。
2. 到学习边界设置，打开“Use my accepted study notes in responses when I select their topic”。这次修改会建立新政策版本，使旧结果失效，所以应在新政策下重新验证/接受需要使用的成果。
3. 发送普通模型任务时，在 Learning context topic 选准确的话题；不选择，就不取学习笔记。TUI 同样先问 Learning context。
4. 仅当另一个单独选项“保存显式标记的任务输入”也打开时，填写稳定的 Current task ID；这只收集你明确打标签的用户任务，不把模型回答冒充用户经验。
5. 检查实际回答是否更贴合，而不是仅看开关已打开。

当前最多取该话题下三条仍新鲜、已接受的笔记作为从属上下文。它们保留来源 ID 和指纹，不能改变规则、角色范围、工具或审批。草稿、未确认观察、过期与失效成果不进入这个通道。

koder-open run '按我的规范起草流程说明，先确认资料缺口。' --topic 工作写作 --task-id actual-task-101 --home "$HOME/KoderLearningData"

若修改角色、切换/重启某个 Skill 或改变学习边界，旧成果会失效。你可能看到复习卡重新 due、学习结果 stale。这是为了防止旧偏好压过新规则；重新检查和练习后再接受，不要把失效标记直接改掉。

每天怎样用：一个可持续的习惯

这是一套由你触发的工作节奏，不是已经开启的后台定时服务。

第一次使用按“配置一份核心规范 → 测一正一反 → 接一个小任务 → 做一张复习卡”推进。稳定后再增加主题与岗位，不用第一天就导入整个资料盘。退出后想继续，只需用同一数据目录、空间和角色重新启动。

不同岗位和领域，具体怎样改

20 个行业模板只是起点。你也可以自己定义任意角色，不被这些名字限制。

每个领域都用同一过程：定义职责 → 准备可靠资料 → 固定规范 → 加正反例 → 机械检查 → 真实代表性任务 → 人工验收 → 改进。任何人的配置都可以不同，但“最懂这个领域”必须由实际表现证明，不能用一个模板标签保证。

怎样判断已经成为“适合我的 KODER”

用代表性任务验证，避免靠一次惊艳或一次失败下结论。

1. 准备至少 10 个实际会遇到的案例：常见任务、信息缺失、范围外请求、规范冲突、错误资料、需要解释原理、需要保持调性、含禁用内容、资料更新和重开恢复。
2. 为每个案例写清：允许用的资料、必需内容、不能发生的行为、什么算合格。
3. 先不接真实外部执行。跑完文本任务，逐项打分，保留失败及原因。
4. 机械失败先修规则或内容；知识失败补可靠资料与复习题；风格失败加具体正反例。不要把所有问题都归因于模型名字。
5. 每次只改少量因素，重测受影响案例；固定版本并记录哪些仍未验证。

这一步完成，表示该版本在这些场景上更适合你，不表示所有专业问题都已通过，更不代表工具宿主、Windows 或外部渠道已经验收。当前 eval 命令还没有接入真实评估 host，使用你的案例表和输出记录做人工评价。

CLI 命令参考与源码入口

下面按实际可用范围列出；高级命令先看状态，不把未接线的命令当成已完成能力。

默认命令名是 koder-open，不是你电脑上可能已有的另一套 koder。先 version 核对。下面省略重复的 --home 时，实际会使用默认数据目录；跟着本教程练习时应统一补上自己的目录。

koder-open config show --json --home "$HOME/KoderLearningData"
koder-open config diff /voice/detail brief --home "$HOME/KoderLearningData"
koder-open config set /voice/detail brief --home "$HOME/KoderLearningData"
koder-open config set /voice/locale zh --home "$HOME/KoderLearningData"
koder-open status --home "$HOME/KoderLearningData"

--revision 可指定预期配置版本；版本已被别处修改会拒绝，而不是静默覆盖。--json 输出机器可读 JSON；它不会使不可用功能变成可用。当前 learn 的文件写入会读取最新库版本并用冲突检查提交；接口级更新也有版本门。

给获准拿到源码的内部使用者

node --version
node bin/koder-open.mjs version
node bin/koder-open.mjs tui --home "你的独立数据目录"
node bin/koder-open.mjs setup --home "你的独立数据目录" --port 0

源码运行不需要为这个项目先执行 npm install。拿到私有源码不等于获得产品修改、再分发或商用权限；以实际书面授权为准。普通用户优先用已验证的自包含原生包。

多角色、备份、重开和恢复

数据是否“同一份”，由目录、空间和角色共同决定。

分开两个角色

koder-open role create --role engineering --industry D20 --name '工程学习助手' --home "$HOME/KoderLearningData"
koder-open tui --role engineering --space default --home "$HOME/KoderLearningData"
koder-open config show --role engineering --space default --home "$HOME/KoderLearningData"

学习与导入资料按 tenant/space/role 隔离。只是切到另一个角色，不会自动共享第一份材料；要共享哪份资料，应明确导入、审阅和启用。网页默认管理 default 空间，指定角色需要在 Current role 输入并 Open；更细空间切换用 TUI/CLI。

备份与迁移

1. 先保存所有草稿，停止使用该数据目录的 TUI/Studio 和正在写入的命令，避免复制到一半状态。
2. 通过文件管理器把 configuration、role-library、models 三个目录复制到你自己的受保护备份位置，标注产品版本和日期。它们可能包含私密原文，不要放到公开仓库。
3. 保留你导入前的原文件，它们不是删除 Skill 后自动恢复的来源。单独管理模型 Key；模型配置备份里没有 Key 值。
4. 恢复时先把现有目标目录改名留存，再恢复三份目录到新数据位置；不要用命令盲目覆盖唯一副本。
5. 用 --home 新位置 重开，检查角色、Skill 状态、学习记录和模型设置；新设备/新版本按要求重新授权，不搬运或编辑签名文件来规避绑定。

全量角色回滚示例：先在修改前记下配置版本，后来如果当前版本为 5、目标在保留历史中的版本为 3，可运行：

koder-open rollback --revision 5 --target-revision 3 --home "$HOME/KoderLearningData"

这会恢复整份角色配置的覆盖值并生成新版本，不只是退回语气，也不会复原已经删除的 Skill 或学习记录。它可能使相关学习结果失效；回滚后仍需重新核对。

升级、回退与卸载

先保数据，再处理运行程序。不要为了排错一开始就删数据目录。

Mac 升级与回退

1. 取得团队确认的新包和摘要，核对架构、版本及条款。
2. 关闭自己的运行会话，完成数据备份，再在新包解压目录运行 sh install.sh。
3. 安装器保留受管理前一版和独立数据。用 version、保存重开和代表案例验收升级，不只检查安装脚本退出。
4. 需要回退时，用较新的已解压包中的 sh install.sh --rollback，它只切换到验证通过的受管理前任。没有前任时会返回 ROLLBACK_UNAVAILABLE。旧版安装器不一定能理解新目录系列。

版本与条款绑定签名授权，升级/回退后云模型可能要求重新确认条款或登录；配置保留不表示授权文件可跨版本使用。

卸载的实际效果

Mac 在确认备份并停止相关会话后，可从对应的已解压包运行 sh uninstall.sh。它移除受管理运行文件和 launcher，保留独立用户数据；发现额外/外来文件会拒绝盲删。Windows 当前脚本 .\uninstall.ps1 只移除受管理 launcher，保留版本目录和数据，验收结果见发布状态文件。

这里不提供递归删除全部资料的快捷命令。如果你确实要移除自己的资料，先明确哪份目录与备份属于你，再按自己的数据管理方式处理。卸载本地程序、退出授权或忘记学习数据，都不等于公司私有 GitHub 历史回执、你的外部备份或模型服务记录已被删除。

遇到问题：按现象定位

先看具体状态和错误码，再调整对应一层；不要把所有错误都归为“模型不行”。

联系支持时提供：操作系统/芯片、version 输出、出错命令（删去敏感内容）、错误码、预期与实际结果、使用的 home/role/space 是否一致。不要附 API Key、GitHub token、签名授权文件或真实客户原文。

从入门到熟练：最后自检

完成这些动作，你就掌握了当前版本的定制、使用和恢复方法。

• 我能分清 CLI、TUI 和本地后台，知道什么时候后台还在运行。
• 我核对过程序版本与平台，不把旧公网包和新候选混用。
• 我有明确角色目标、允许范围、方法与可观察的表达标准。
• 我能整理、导入、审阅、启用、停用自己的文本资料。
• 我实际测过一个应该通过、一个应该被拦截的样例。
• 我分清模型 Key、GitHub 设备码、条款摘要和签名授权。
• 我知道当前发布方服务未配置时，真实模型请求不会成功。
• 我能给真实问题添加任务 ID，不编造独立证据。
• 我会做预习、复习、补课、预演；知道模拟不是执行完成。
• 我会复核学习成果；只有开启允许复用并选对话题时才用它。
• 我能按真实案例评价是否适合自己，并保留未通过的问题。
• 我知道如何暂停、忘记、备份、重开、切角色和回滚配置。

你的“专用 KODER”不是一份一次写完永不改变的提示词，而是一组由你维护的目标、范围、可靠材料、方法、正反例、输出检查与被确认的学习成果。扩充资料之后持续做小规模验证，它才会逐步贴近你的领域与调性。

发布方：建立免费 HTTPS 授权服务

普通用户不需要做这一章；团队管理员在这里配置真实服务，用户资料仍留在本机。

当前选择 Render 免费 Node 实例、新加坡区域，暂不付费。一个工作区每月 750 个免费运行小时，闲置 15 分钟会休眠；还有流量与构建额度。没有供应商能保证未来永久免费，不使用保活请求绕过限制。Cloudflare Workers 有免费额度，但本产品的 Node 服务尚未在该运行时适配验收。

1. OAuth App 已在 KarmenLoop 创建，公开 Client ID 为 Ov23li7TL02qaztlNEIc，Device Flow 已启用；无需向客户端加入 Client Secret。
2. 回执仓库使用专用 Private 仓库；服务 Token 只允许该仓库 Contents 读写。Token 不进入客户端、教程或聊天。
3. 从私有源码根目录运行 bash scripts/publisher-setup.sh。向导只保存公开 Client ID、HTTPS origin 和本机公钥文件路径；私钥与 Token 由账号持有人直接放入 Render Secret。
4. Render 登录后验证公司邮箱，连接 GitHub 时只选择源码仓库，使用 render.yaml，核对 Free、新加坡和关闭自动部署。
5. 服务启动后核对 /healthz 的版本、条款摘要、Client ID 与本机公钥指纹；把真实 HTTPS origin 和公钥写入客户端公开配置，重新构建 Mac 与 Windows。
6. 最后做真实下载、条款同意、GitHub 激活、私有回执读回、资料导入和 CLI/TUI 两次 DeepSeek 合成请求。逐项记录实际结果；健康检查和打包成功都不能代替完整验收。

bash scripts/publisher-setup.sh

完整变量表、界面点击位置、密钥备份与恢复及逐项验收步骤在源码仓库 docs/PUBLISHER_RENDER.md。普通 Windows 用户只需使用已配置的发行包，不需要 Bash、服务器 Token 或私钥。

免费实例休眠时，先运行 koder-open auth wake --home 你的数据目录，最多等待 60 秒。看到 issuer-ready 后再开始 GitHub 登录。TUI 的 Model and GitHub license 菜单及网页条款页也有 Wake and verify authorization service。它只核对公钥指纹、App、版本和条款，不会激活、自动重试或切换服务。

2026-10-21 当前状态：OAuth App、Device Flow、签名与免费 HTTPS 服务均已配置。服务地址为 https://koder-open-issuer.onrender.com；Mac 已安装客户端完成真实 GitHub 激活，签名通过且私有回执未重复创建。各平台安装、CLI/TUI 模型调用结果以当前发布验收记录为准。

官方依据：Render 免费限制、Workers 免费额度、GitHub Device Flow。

样例文件、来源与版本记录

所有样例用于你自己的独立练习环境；模型和授权类步骤没有在你的真实账号上代做。

下载全部可编辑样例 ZIP。解压后保留 examples 文件夹结构，在教程所在文件夹执行形如 ./examples/… 的命令。不要从压缩包内部直接运行命令；先解压。

本轮模型与发布方配置

DeepSeek 完整端点为 https://api.deepseek.com/chat/completions，协议选 Chat Completions。本轮账号实际列出 deepseek-flash 与 deepseek-v4-pro，验证使用 deepseek-flash。请以你自己的账号当前模型列表为准；教程与配置都不包含密钥。

发布方已创建源码私有仓库与专用私有回执仓库。本版客户端已配置真实 HTTPS issuer、公钥与产品 OAuth App；Device Flow 已建立。发布方操作参见 PUBLISHER_SETUP.md，普通用户无需创建回执仓库。

本教程的证据边界

文档依当前实现与实测流程编写；功能入口按产品源码、安装器、角色 schema、模型/授权实现、CLI 与 TUI 实际流程编写。样例已在自有合成数据目录按实际命令验证；最终测试结果另有验收记录。本轮在已安装 Mac 客户端使用授权的 DeepSeek 账号，仅发送合成文字，实际模型为 deepseek-flash；CLI 和 TUI 均已返回完整回答并通过已投喂规范的机械检查。首次小额度请求被拦截，增加明确思考模式设置后再验收，没有自动重试。产品 OAuth App 已注册、Device Flow 已启用，本机签名密钥已准备；HTTPS 服务已上线，已安装 Mac 客户端完成签名激活。每位最终用户仍需自行阅读并接受条款。Windows 原生安装和 ConPTY TUI 已通过；按用户选择，没有向 GitHub 上传模型 Key，Windows 真实模型调用仍未验证。后续各平台激活结果见当前发行页验证记录。

外部参考只用于相应基础操作，不替代本产品实际实现：Node 下载、GitHub 设备流程、PowerShell 执行策略。核对日期：2026-10-20。模型名、控制台和官网内容可能变化，以实际账号和官方页面为准。

发布方：KARMENLOOP 团队，中国上海；官网 karmenloop.com，邮箱 info@karmenloop.com。法律文件以安装内展示的具体版本为准，教程不扩大授权。