Skip to content

docs: add Turn, Tier, and Budget entries to the glossary - #1879

Open
Kiuyor wants to merge 2 commits into
TokenRhythm:mainfrom
Kiuyor:docs/glossary-turn-tier-budget
Open

Kiuyor wants to merge 2 commits into
TokenRhythm:mainfrom
Kiuyor:docs/glossary-turn-tier-budget

Conversation

@Kiuyor

@Kiuyor Kiuyor commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

Scope

Scope boundary: 只改 docs/glossary.md(纯文档)。按文件既有格式(2~3 行定义 + Read: 指针指向已有用户文档)新增三节,位置保持字母序,条目数 17 → 20:

  • ## Budget:每回合(turn)检查的额度上限;六个 per-turn 门计数 LLM 调用、输入/输出 token、成本(billed 及估算同族)与工具错误,附件磁盘是另一根轴、另有自己的预算。
  • ## Tier:SquillaRouter 路由用的四个文本档位 c0–c3;t0–t3 是归一化到它们的 legacy 名,R0–R3 是同一映射的路由类;并注明 T0–T3 另被推理档位复用(同名字母、另一根轴)。
  • ## Turn:一次用户可见请求及智能体为回答它做的全部动作(重复 LLM 调用、工具调用、推理);预算与成本汇总以 turn 计数。

三节都写成指针、不复述门限数字与具体模型名——三个词的实质定义已各有一处权威:docs/providers-and-models.md(Turn and Router Budget Gates)、docs/features/squilla-router.md(C0–C3 档位表)、docs/diagnostics-and-replay.md。

Non-goals: 不改代码、不改其他文档;不在 glossary 里正式裁决 tier 别名债(issue #1874 里已提出"三套别名 id 是否该在 docs/features/squilla-router.md 正式裁决"的开放问题),也不新增 Adjudication point 一节(该词没有 .md 归宿,issue 中列为需维护者先裁决的开放点)。

Branch

Base branch: main

Target exception: N/A

Issue

Linked issue: Fixes #1874

If None, reason: N/A

Release Note

Release note: NONE

Tests

Ruff: uv run ruff check src tests — All checks passed

Pytest: uv run pytest tests/test_release_consistency.py -q — 70 passed, 2 skipped

Build: npm --prefix opensquilla-webui run build — 通过(Web UI artifact verified: 156 files,已按仓库流程 stage 给打包);uv build --wheel — 成功(opensquilla-0.5.6-py3-none-any.whl)

Regression tests: not needed

Notes: 纯文档改动(只在 docs/glossary.md 新增三节),不涉及行为;三个新增 Read: 链接目标均已存在于仓库。

本机为中文 Windows,另外完整跑了 CI 同款两相全量(marker 过滤与 CI 三处 job 逐字一致;并行相 -n 8 --dist loadfile):

  • 并行相(-m "<CI 过滤> and not ci_serial"):31981 passed / 728 skipped / 38 failed
  • 串行相(-m "<CI 过滤> and ci_serial"):313 passed / 5 skipped
38 条失败的逐条归因(全部与本次改动无关;对照实验:`git stash push -- docs/glossary.md` 后同机复跑同一批 38 条,失败集合逐条一致,pop 后恢复)
  • 28 条 WinError 1314(客户端没有所需的特权):本机没有创建符号链接的权限(未开开发者模式)
  • 4 条 Git-Bash → 原生 Python 的 /tmp 路径互操作(test_prestage_release_to_oss ×2、test_release_oss_mirror_workflow ×2)
  • 2 条本机 PATH 缺 python3(test_workspace_write_deny_levers 的用例硬编码 python3 命令)
  • 1 条 gh 不在 PATH(test_skill_catalog_projection:github 技能声明 requires: bins: ["gh"],本机 gh 装在 PATH 之外)
  • 1 条本机 ANSI 代码页(GBK)进入子进程输出编码嗅探(test_bounded_output_capture 的行计数用例)
  • 1 条本机系统代理(注册表层)进入 httpx 默认挂载(test_live_tokenrhythm_transport 期望的 Mock 挂载被遮蔽)
  • 1 条为 4494195 上游自带红:tests/test_ci/test_workflows.py::test_release_jobs_share_one_rerun_stable_verified_webui_artifact —— wheelhouse-release.yml 中 fix(release): validate existing Draft upgrades without rebuilding #1871 新增的两个 upload-artifact@v4 步缺 overwrite: true,而该提交 [skip ci] 合入未跑 CI;本 PR 不涉该文件,供维护者参考

本机跑 pytest 另需 PYTHONUTF8=1(GBK 区域默认编码会让 tests/contracts/test_page_context_contract.py 在收集期抛 UnicodeDecodeError;UTF-8 环境不触发)。

The default test path remains offline, deterministic, credential-free, and safe for forks.

Maintainer Live Check

Maintainer live check: no

Surface: N/A

Maintainer-only note: contributors are not expected to provide secrets or run credentialed live checks. Maintainers may run Live Release E2E for provider, browser, gateway, channel, or release smoke coverage.

Safety

Secrets, local-only artifacts, private prompts/transcripts, channel identifiers, AI session artifacts, non-public fixtures, and tests/_private/ contents must not be committed.

Third-Party Origin

Third-party origin: none

Details if non-none: N/A

Documentation Changes

  • Links point to existing repository files or stable external pages.
  • Code fences and Markdown tables render correctly on GitHub.
  • Examples avoid real secrets, local private paths, and private transcripts.

Three terms the docs already lean on in other definitions have no
glossary sections of their own: budget, tier, and turn. Add pointer
entries so readers land on the existing authorities:

- Budget: per-turn gates (LLM calls, tokens, cost, tool errors) plus
  the separate attachment-disk axis.
- Tier: the four text tiers c0-c3, legacy t0-t3 aliases and R0-R3
  route classes, plus the T0-T3 reasoning-level overload note.
- Turn: one user-visible request including its nested LLM and tool
  calls; budgets and cost rollups count turns.

Entries stay two-line pointers without thresholds or model names.

Tests: docs-only; `uv run ruff check src tests` clean; docs-consistency
suite passes (70 passed, 2 skipped); full-suite local results documented
in the pull request.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: turn / tier / budget 在 glossary 查不到,且 T0–T3 两种含义(路由档位 / 推理档)易混——建议补三节指针

2 participants