coding

Coding Examples

examples/coding/ contains loushang-coding 的可执行示例与一个统一入口。

一键初始化

执行以下命令可一键生成示例运行所需的本地骨架：

cd /home/dev/workspace/loushang
uv run python examples/coding/init_examples_env.py

会默认创建（并写入说明）：

• examples/coding/.loushang/：运行时根目录
• examples/coding/.loushang/sessions/：会话落盘目录
• examples/coding/.loushang/extensions/：示例扩展文件目录
• examples/coding/.loushang/models/：可选自定义模型 catalog 目录

建议将该目录和你的示例会话一起提交为“本地运行环境脚手架”，从其他机器 git pull 后再跑一遍初始化即可重建同结构，脚本输出可直接执行的推荐环境变量和命令。

可选参数：

python examples/coding/init_examples_env.py --help
python examples/coding/init_examples_env.py --dry-run
python examples/coding/init_examples_env.py --copy-model-catalog --overwrite

--copy-model-catalog 只用于需要本地定制时复制内置 catalog 快照；常规示例直接使用 src/loushang/ai/model/models.json，无需复制。

统一运行器

从 bash 执行：

cd /home/dev/workspace/loushang/examples/coding
python run.py list
python run.py list --category sdk
python run.py list --tag toolset --count
python run.py run legacy-001
python run.py run legacy-001 --dry-run

参数说明：

• list: 列出示例。支持 --category/--tag/--query/--count/--json
• run <id|slug>: 运行指定示例，支持透传参数到原始脚本
• --json: 机器友好输出

run.py 基于 example-manifest.toml 统一管理 231 个示例（包含： 33 个可执行脚本 + 198 个生成示例）。

直接运行单个示例

run.py 是推荐的统一入口，但不是强制入口。现有脚本都可以直接执行，适合调试单个例子或临时传参：

cd /home/dev/workspace/loushang
uv run python examples/coding/21_switch_model_route.py
uv run python examples/coding/22_usage_inspect.py --endpoint kimi-code-anthropic --strict
uv run python examples/coding/25_render_tool_events_contract.py
uv run python examples/coding/extensions/01_lifecycle.py
uv run python examples/coding/arch/01_import_graph.py

架构分析示例直接使用公共 loushang.coding.arch API；更多说明见 arch/README.md。仓库自动化使用的 scripts/arch 入口不作为用户示例。

如果已经激活本仓库虚拟环境，也可以直接用 python：

cd /home/dev/workspace/loushang
source .venv/bin/activate
python examples/coding/21_switch_model_route.py

直接运行时需要注意：

• 建议从仓库根目录执行，保证 src/loushang 能被当前环境解析。
• 如果出现 ModuleNotFoundError: No module named 'loushang'，优先使用 uv run python ... 或激活 .venv。
• 需要自定义模型 catalog 时，可通过环境变量传入：LOUSHANG_EXAMPLES_MODEL_CATALOG=examples/coding/models。
• 需要会话/产物目录时，可设置：LOUSHANG_EXAMPLES_ARTIFACT_ROOT=examples/coding/.loushang。
• run.py run <id|slug> 额外提供 manifest 查询、dry-run、统一环境变量透传和脚本参数透传；直接运行则更接近“脚本原生行为”。

设计路线（online 优先 + 可复现）

本地验证与证据消费（私有集成示例）

26_verification_evidence.py 通过真实 Coding Session 执行本地检查，利用原 Work 完成报告与验证两步，再从日志及 Session Blob 重读证据。该示例不调用模型，无需 API key； 当前直接运行，未加入统一运行器。私有适配尚非稳定公共 SDK 接口。

从仓库根目录运行，使用新的、仅自己可写的本地输出目录；状态域与数据域分开：

export LOUSHANG_HOME="$(mktemp -d /tmp/loushang-verify-state.XXXXXX)"
evidence_dir="$(mktemp -d /tmp/loushang-verify-evidence.XXXXXX)"
uv run python examples/coding/26_verification_evidence.py \
  --workspace "$PWD" --output-dir "$evidence_dir" \
  --command 'uv run python scripts/ci/check_docs.py'
uv run python examples/coding/26_verification_evidence.py \
  --output-dir "$evidence_dir" --reopen

第二条命令只重开并消费原证据，不再次执行检查。成功输出包括 Work completed、 verification_passed=true、材料健康状态和实际读取的报告/验证 JSON。 短输出可保存为明确标注的 SDK 文本视图；缺失、损坏、不完整或失败均不能冒充验证通过。 本例只验证一条命令，不能由材料可读或 Work completed 推断 Goal 完成。

从 coding 侧这套路线继续往下走，采用三个锚点：

• 学习目标：每个例子先定义“验证哪个能力是否成立”。
• 运行形态：默认走 online，能离线验证的例子保留 offline fallback。
• 观测点：每个示例都要能输出 message/start/end、tool.start/end、resolved catalog、会话文件变化、错误码与返回摘要。

建议执行时按 pi-mono 风格阅读映射：

• sdk-*：SDK 与模型通路（会话构建、鉴权、路由、重试、降级）
• ext-*：扩展生命周期与 hook
• skill-*（新增）：Skill 注册、发现、调用与回退
• model-*（新增）：provider/endpoint/模型参数一致性与健康检查
• provider-*（新增）：自定义 provider、OAuth、payload、streaming 与降级
• config-*（新增）：settings/env/catalog/session 的配置一致性
• run-*：运行器语义、会话恢复与落盘
• rpc-*：RPC mode、命令与会话查询面
• cmd-*（新增）：slash/prompt/skill/extension 命令发现、解析、路由与执行
• interaction-*：简单交互
• prompt-*：系统提示词
• compaction-*：compaction 策略
• ui-*（新增）：UI/render/status/editor/overlay 的文本与事件投影适配
• git-*（新增）：checkpoint、auto-commit、dirty repo guard
• tools-*：工具链（bash/write/tool list）
• stepwise-*：无渲染分步编码

说明：当前生成型入口新增了 model/skill/config，用于补齐 pi-mono 组件齐全性；实际脚本先对齐现有 25 个（legacy-*）后再逐步迁移 id 命名。

更完整的路线说明见 EXAMPLE_DESIGN_ROADMAP_2026-05.md。

主题前缀（按生成+既有脚本）：

• sdk-*：SDK 相关
• ext-*：extensions 相关
• model-*：模型通路（provider/endpoint/catalog）
• provider-*：自定义 provider 与鉴权/streaming 适配
• skill-*：skill 生命周期与调用
• config-*：配置、环境变量与会话路径
• run-*：run 体系
• rpc-*：RPC mode 与命令查询面
• cmd-*：用户命令面（slash/prompt/skill/extension）
• interaction-*：简单交互（simple_interaction）
• prompt-*：系统提示词
• compaction-*：短窗口 compaction
• ui-*：UI/render/status/editor/overlay 适配
• git-*：Git 集成与安全守卫
• tools-*：toolsets
• stepwise-*：step_by_step_coding（无渲染）

pi-mono 覆盖跟踪见 PI_MONO_COVERAGE.toml。覆盖状态含义：

• covered：已有可运行 loushang example 验证同一学习目标。
• partial：已有能力域覆盖，但缺少专门脚本或关键观测点。
• planned：已进入 manifest/coverage，尚未实现具体脚本。
• deferred：依赖 loushang 核心能力或 UI 形态，暂缓。
• not_applicable：pi-mono TUI/平台细节，不迁移为 coding 主线示例。

可复现流程

建议流程（任何机器上可复现）：

cd /home/dev/workspace/loushang
uv run python examples/coding/init_examples_env.py
export LOUSHANG_EXAMPLES_ARTIFACT_ROOT=examples/coding/.loushang
uv run python examples/coding/run.py list --count

默认模型 profile 已调整为：

• coding_primary => provider=kimi-code, endpoint=kimi-code-anthropic, model=kimi-for-coding

3 秒判断：默认/显式

• 默认走 kimi-code/kimi-code-anthropic（Anthropic 兼容协议）。
• 显式指定 kimi-code-openai 时走 OpenAI 兼容协议。
• Kimi Code 两条协议都支持 k3（当前旗舰）和 kimi-for-coding（K2.7）；示例 profile 暂时固定 kimi-for-coding 以保持可复现。
• KIMI_MODEL_NAME 仅作为模型名提示变量；在示例缺省路径里不会强制切换 endpoint。

说明：provider:endpoint:model 中的 endpoint 只接受 registry 中的 endpoint id。 Kimi Code 在内置 catalog 中提供 kimi-code-openai 与 kimi-code-anthropic 两条路由。

未指定 --model-catalog 时，示例只读取内置 catalog。仓库不再提供会遮蔽内置配置的 Kimi Code 示例 catalog。

补充：Kimi Code 使用自己的模型 ID：当前旗舰写 k3，K2.7 coding 路线写 kimi-for-coding，不要写 Moonshot 平台的 kimi-k3 或旧的 kimi-k2.5。

Kimi 环境变量模板（按你这个模型名）

如果你要用 Kimi 官方建议的模型名：

source examples/coding/kimicode.env.example

模板内容（可按需改）：

export KIMI_CODE_API_KEY="sk-xxx"
export KIMI_MODEL_NAME="kimi-for-coding"  # 缺省路径下仅作兼容变量，不影响 endpoint 选择

注意：KIMI_CODE_API_KEY 与 Moonshot 开放平台的 MOONSHOT_API_KEY 分属不同 provider 配置，示例不再交叉回退到 Anthropic、OpenAI 或 Moonshot 平台 key。

如果你不想每次都手工设置环境变量，也可以在运行时直接指定参数：

python examples/coding/run.py --artifacts-root examples/coding/.loushang \
  --session-dir examples/coding/.loushang/sessions \
  --extensions-dir examples/coding/.loushang/extensions \
  list --count

若只想跑单个脚本，不依赖仓库根目录约定，可直接进入目录：

cd /home/dev/workspace/loushang/examples/coding
python run.py run legacy-001

为避免 import loushang 解析失败，run.py 在执行子示例时会自动注入仓库 src 到 PYTHONPATH。 你在仓库其他机器上 git pull 后，只要按同样路径运行就能直接启动：

cd /home/dev/workspace/loushang
python examples/coding/run.py run legacy-001

建议采用固定目录约定（都放在仓库内，便于 pull 后复用）：

• ~/<repo>/examples/coding/.loushang/：示例运行时总目录（本仓库默认）。
• ~/<repo>/examples/coding/.loushang/sessions/：会话落盘目录（默认值，对应 persist=True 的示例）。
• ~/<repo>/examples/coding/.loushang/extensions/：示例扩展文件可存放目录（供需要读取本地扩展时使用）。
• ~/<repo>/examples/coding/.loushang/models/：可选模型清单目录；只有显式选择该目录时才作为覆盖 catalog。
• ~/<repo>/examples/coding/models/：自定义 catalog 示例位置；仓库不在这里提供默认 provider 数据。
• ~/<repo>/.loushang/settings.json：可选本地配置（如需覆盖模型/提示词/会话目录时）。

run.py 的运行时约定会透传如下环境变量给子进程：

• LOUSHANG_EXAMPLES_ARTIFACT_ROOT
• LOUSHANG_EXAMPLES_EXTENSIONS_DIR
• LOUSHANG_EXAMPLES_SESSION_DIR
• LOUSHANG_EXAMPLES_MODEL_CATALOG（当前支持 json 文件或目录）

你可以把自定义目录固定到仓库内，跨机器 pull 后重用：

cd /home/dev/workspace/loushang
export LOUSHANG_EXAMPLES_ARTIFACT_ROOT=examples/coding/.loushang
export LOUSHANG_EXAMPLES_MODEL_CATALOG=examples/coding/models
python examples/coding/run.py list --count
python examples/coding/run.py run legacy-001

LOUSHANG_EXAMPLES_MODEL_CATALOG 不设时，示例 helper 会优先读取： <artifacts-root>/models/（目录）； <artifacts-root>/models.json（文件）； 找不到再回退到内置 src/loushang/ai/model/models.json。

models.xx.json 这类模型清单建议放在示例目录的 models/ 下（例如 examples/coding/models/）， 并在需要时通过：

python examples/coding/run.py run legacy-014 --model-catalog examples/coding/models

来使用；默认仍为 src/loushang/ai/model/models.json。

Kimi Code 的 provider、两条兼容协议路由以及 k3、kimi-for-coding 模型都由内置 catalog 维护。init_examples_env.py --copy-model-catalog 仅复制该内置文件作为用户 定制快照，不会再叠加示例目录中的 provider 模板。

若你习惯在 examples/coding 目录直接运行，也可直接执行：

cd /home/dev/workspace/loushang/examples/coding
python run.py list --count
python run.py run legacy-007

会话与模型目录的执行优先级为：

1. CLI 参数（--session-dir/--artifacts-root/--model-catalog）
2. 对应环境变量（LOUSHANG_EXAMPLES_SESSION_DIR 等）
3. 默认路径（~/<repo>/examples/coding/.loushang）

现有脚本总览

Main Path

• 01_minimal.py: smallest online session with a custom calculator tool
• 02_custom_model.py: use a manually selected model
• 03_custom_prompt.py: customize the system prompt
• 04_builtin_bash_tool.py: enable the built-in bash tool
• 05_model_with_builtin_bash.py: combine a custom model with built-in tools
• 06_nl_with_builtin_bash.py: natural-language tool usage with bash
• 07_offline_session_restore.py: offline runtime, persist, and restore a session
• 08_online_resume_repo_session.py: resume a repo session against a real model
  • use --timeout <seconds> to avoid long hangs when the model endpoint is slow/unreachable
• 09_print_mode_text.py: run PrintMode in text projection
• 10_print_mode_json.py: run PrintMode in JSON projection, optionally with rendered tool events
• 11_cli_commands.py: exercise CLI command list/execute flow
• 12_cli_session_surface.py: exercise CLI session naming/listing/export flow
• 13_rpc_mode_probe.py: exercise RPC mode discovery and lightweight state mutation flow
• 14_simple_code_writer.py: simple natural-language coding request that writes files through bash
• 15_simple_write_tool.py: minimal natural-language coding request that writes files with the write tool only
• 16_write_tool_trace.py: readable assistant/tool trace for a coding request
• 18_kimi_runtime_matrix.py: offline matrix of endpoint -> base_url -> api -> model
• 19_session_store_check.py: verify session persistence and list/index consistency
• 21_switch_model_route.py: validate route switch across candidate endpoints
• 22_usage_inspect.py: model usage/cost extraction and unified print format
• 23_kimi_weekly_usage_ledger.py: local weekly ledger based on response usage, with rolling aggregation and an optional local budget
• 24_git_checkpoint.py: git stash checkpoint as an AgentTool with offline mock + optional live path
• 25_render_tool_events_contract.py: offline JSONL example for renderedToolCall/renderedToolResult
• 26_compaction_summary_evaluation.py: offline summary quality evaluation for compaction output, with optional --real model run
• skill_02_advanced.py: disable-model-invocation filtering and system prompt <available_skills> XML injection
• config_01_resource_layers.py: flat resource architecture four-layer precedence (project > user > external > built-in)

06_nl_with_builtin_bash.py, 08_online_resume_repo_session.py, 09_print_mode_text.py, and 10_print_mode_json.py require an explicit request argument. Running them without a request prints usage and exits.

Extension Path

Extension-focused examples live in extensions/README.md.

They are intentionally offline and self-contained:

• they create a temporary project directory
• they write an extensions/*.py file using the current register(api) protocol
• they run a local offline session/runtime to demonstrate the hook or tool behavior

Start there if you want to learn the current ExtensionAPI v1 surface.

Commands Status

The command descriptor surface is now test-backed in the core coding package and has a dedicated example. It follows the pi-style session aggregation model rather than a standalone command registry class.

Current stabilized pieces:

• RPC get_commands delegates to AgentSession.list_commands() and can return extension, prompt, and skill entries
• slash-prefixed extension commands are consumed before prompt/skill expansion reaches the model
• queued steer / follow_up inputs reject extension slash commands instead of executing them later
• extension input hooks can handled or transform user input before prompt/skill expansion
• extension command argument completions are available through the session/runner query surface
• CLI supports extension-registered flags through a two-pass startup parse
• CLI --session-name writes session metadata for later introspection and listing
• CLI model listing keeps the default text output and supports --list-models-format json for structured consumers
• CLI session listing supports --list-sessions with TSV output by default and --list-sessions-format json
• CLI command listing keeps the default TSV output and supports --list-commands-format json for structured consumers
• CLI command execution keeps raw result output by default and supports --command-result-format json
• CLI session export supports bare --export, --export-format html|jsonl, and --export-result-format json

本地 Goal 最小修复闭环

27_goal_calculator.py 复制固定缺陷项目，通过原 Coding SDK 和真实 Kimi 模型， 完成“初始失败验证 → 显式 Method 修复 → 独立再验证”，再读取 Goal 完成依据。 模型只使用原 read/edit/write；验证使用原 SDK 命令路径。需要现有 Kimi 凭据。

uv run python examples/coding/27_goal_calculator.py --output-dir /tmp/calculator-goal-demo
uv run python examples/coding/27_goal_calculator.py --output-dir /tmp/calculator-goal-demo --reopen

首次选择不存在的输出目录；--reopen 只读取原身份和材料，不创建模型 Session 或重新执行工作。若继承的 LOUSHANG_EXAMPLES_MODEL_CATALOG 指向旧目录， 可清空该变量使用内置模型目录。支持范围和失败约束见 Goal 实现记录。

首次 Work 的 failed 是固定缺陷项目的预期检查结果，不代表 Goal 失败。 后续模型修复期间每五秒输出 advance_in_progress，包含当前 Work 状态和步骤； 这只是等待进度提示，不代表步骤已完成。最终以 status: completed 且 validity: current 为成功。按 Ctrl+C 会通过原关闭路径取消工作，保留记录； --reopen 只读检查，不会续跑，也不会把已修改的源码直接判为 Goal 完成。

模型逐批规划（当前限定计算器任务）

同一个例子加 --model-planning，由模型基于当前材料与实际结果选择下一批工作。 系统核验候选后，通过原 Work 执行 inspect、check、Method repair 或 verify_all。 模型提出的后续路线只是建议，不能直接完成 Goal、修改要求或扩大权限。

goal_demo="$(mktemp -d /tmp/loushang-model-goal.XXXXXX)"
uv run python examples/coding/27_goal_calculator.py --output-dir "$goal_demo/run" --model-planning
uv run python examples/coding/27_goal_calculator.py --output-dir "$goal_demo/run" --reopen

需要现有 Kimi 凭据，第一条执行命令会调用真实模型。SDK 对应入口为 CodingGoal.open(workspace=..., data_root=..., model=..., model_planning=True)； 默认 False 保留显式 Method 方式。当前仅支持这一固定业务 profile，尚不接受任意 Coding 目标；首版不支持跨进程恢复控制，--reopen 是只读复核。

推进中输出规划和原 Work 关联，并导出 planning-trace.json 供观察；重开从原始 Goal/Work/Transcript/Blob 重建规划轨迹，不把导出文件当作事实权威。完成有效性与 规划来源健康分别显示，缺来源时 planning 为 unknown。暂停时查看 goal_reason， 不把 Work completed 当作 Goal 完成。

此模式固定最多 20 个 Work 意图、10 次规划，连续 3 次无效提案或 2 次无进展后停止； 不是 token、费用或时间硬上限。真实模型规划→修复→独立验证已有成功记录；实际 改变路线后完成的动态重规划证据仍待真实开发任务补齐，见实施记录。

29：托管 Method → Work SDK 闭环

运行 python examples/coding/29_hosted_method.py，通过实际 AppHost / AppService 执行固定的 inspect → verify Method，并查询原 Work 与记录确认。示例使用确定性 离线模型，不需要 API key，也不产生模型费用；默认创建新临时目录。 预期输出 execution=succeeded、work=completed。只覆盖应用内 SDK 与内存 Work， 不提供进程恢复或远程协议；详见交付记录。

30：托管 Goal 最小业务闭环

运行 python examples/coding/30_hosted_goal.py，通过真实 AppHost / AppService 与 同一个 canonical Session 执行 calculator 的逐批规划、固定 Method 修复和独立验证。 示例使用确定性的离线 provider，无网络、API key 或模型费用；默认创建新临时目录。 预期输出 execution=succeeded、Goal status=completed、validity=current， 并列出原 Work 身份和独立记录确认。这个试验验证托管集成，不重复证明模型规划能力。

入口为 create_coding_goal_application(launch, CodingHostedGoalV1(...), model=...)， 经 scope.goal_client.start/query/wait/interrupt/retry_settlement 控制。固定最多8次 推进、8次逻辑模型调用、每次1024输出tokens、provider单次尝试，业务期限120秒； 清理可能继续等待，不保证120秒内释放资源。应用关闭前仍可换scope查询；没有远程 协议或重开推进。result.json只是展示结果，不能用于恢复执行。