kirin-tor-cli 0.3.0rc3__tar.gz

kirin_tor_cli-0.3.0rc3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirin Tor contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kirin_tor_cli-0.3.0rc3/MANIFEST.in

@@ -0,0 +1 @@
+prune examples

kirin_tor_cli-0.3.0rc3/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: kirin-tor-cli
+Version: 0.3.0rc3
+Summary: A game-neutral, file-driven theorycrafting CLI and local browser workbench
+Author: Kirin Tor contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Aaronlves/Kirin-Tor-Calc
+Project-URL: Repository, https://github.com/Aaronlves/Kirin-Tor-Calc
+Project-URL: Issues, https://github.com/Aaronlves/Kirin-Tor-Calc/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib<3.10,>=3.8
+Requires-Dist: sympy<1.15,>=1.13
+Requires-Dist: tomli<3,>=2; python_version < "3.11"
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Dynamic: license-file
+
+# Kirin Tor
+
+Kirin Tor 是一个游戏中立、文件驱动的结构化数学工作台，面向需要长期维护数据、公式、参数方案和图表的攻略与理论计算作者。
+
+工作区只有一种可编辑权威：`entries/**/*.kirin`。结果、图表、公式展开、诊断、关系图、索引、恢复缓存和导出文件都是源码的投影或产物，不会形成第二套计算定义。具体游戏的量纲、公式和数据由工作区或独立社区 Package 提供；Kirin Tor 核心不内置游戏、职业、技能或版本数据。
+
+Kirin Tor 不是脚本式战斗模拟器。内核只执行 source 明确声明且受 horizon、事件、决策、分支、实体和
+集合容量约束的 Process 事件场景；它不会补全完整 APL、Boss 时间轴或未声明规则，也不做隐式抽样。
+Process Analysis 已接入 CLI、浏览器工作台实时投影、多图导出和可重放运行记录。
+
+## 安装
+
+Kirin Tor 需要 Python 3.9 或更新版本。长期使用推荐先按
+[`uv` 官方说明](https://docs.astral.sh/uv/getting-started/installation/)安装 `uv`，再让它为 Kirin Tor
+维护独立环境。当前版本仍是预发布版，因此安装和升级时需要显式允许预发布版本：
+
+```bash
+uv tool install --prerelease allow kirin-tor-cli
+kt version
+kt web
+```
+
+以后升级仍使用同一独立环境，不需要进入源码目录或手动激活虚拟环境：
+
+```bash
+uv tool upgrade --prerelease allow kirin-tor-cli
+```
+
+正式版发布后，上述安装和升级命令可以省略 `--prerelease allow`。不再需要时可以完整移除：
+
+```bash
+uv tool uninstall kirin-tor-cli
+```
+
+也可以从 [GitHub Releases](https://github.com/Aaronlves/Kirin-Tor-Calc/releases) 下载 wheel，手动安装到自行管理的虚拟环境：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install /path/to/kirin_tor_cli-VERSION-py3-none-any.whl
+kt version
+```
+
+也可以直接安装当前源码：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install .
+kt --help
+```
+
+开发安装：
+
+```bash
+python -m pip install -e '.[dev]'
+pytest
+```
+
+## 快速开始
+
+创建并打开一个空的游戏中立工作区：
+
+```bash
+kt init my-math
+cd my-math
+kt web
+```
+
+浏览器工作台会显示三份只读教程：基础公式、参数方案与比较、扫描与图表。教程不是工作区文档；只有主动复制后，才会以普通未保存草稿进入校验和保存流程。
+
+也可以从命令行创建文档：
+
+```bash
+kt new entry basic_model --template model
+```
+
+一份最小而完整的 Kirin Tor source 如下：
+
+```text
+@kirin 2
+@entry basic_model "基础公式"
+
+input unit_price "单价": number[dimensionless] = 12 in 0..*
+input quantity "数量": number[dimensionless] = 5 in 0..100 integer
+input discount "折扣": probability = 10%
+
+field subtotal "小计": dimensionless = unit_price * quantity
+
+output total "折后总价": dimensionless = subtotal * (1 - discount)
+display total = number digits 2
+```
+
+保存为 `entries/basic_model.kirin` 后可以校验和计算：
+
+```bash
+kt check
+kt eval basic_model.total
+```
+
+结果为精确值 `54`。十进制先转换为精确有理数，不经过二进制浮点近似。
+
+## 浏览器工作台
+
+`kt web [WORKSPACE|SOURCE.kirin]` 启动只监听本机回环地址的浏览器工作台。服务使用随机会话令牌，不接受外部 Host、跨站 Origin 或远程监听；停止终端进程即可关闭，不存在后台守护程序或云端账户状态。
+
+工作台的主要能力包括：
+
+- 在中央 CodeMirror 编辑器中完成全部源码编辑；`Ctrl+Space` 提供 Kirin Tor 补全和中文结构片段。
+- 同时保留多个未保存草稿，按完整工作区校验，并通过 Save All 原子写入。
+- Agent 或其他本地工具直接改写 `.kirin` 后，干净文档与新文档会自动同步；未保存草稿不会被覆盖，也不会显示 CLI 或 Agent 操作记录。
+- 自动派生只读结果、静态图表、Process Analysis 多图、公式、诊断和局部关系；检查器不提供临时计算参数或参数方案填写字段。
+- 提供定义跳转、引用查找、符号大纲、签名提示、安全重命名、查找替换和安全空白格式化。
+- 提供工作区全文搜索、草稿式批量替换、保存前变更审查、只读 Git 摘要和外部冲突三方合并。
+- 支持文档路径移动、复制为新草稿，以及依赖安全的可恢复删除；这些文件操作不会改写源码中的 `@entry` ID 或数学语义。
+- 从已校验引用生成文档与成员关系图，并为图表和画布提供键盘可读的数据列表。
+- 通过独立本地进程执行长操作，显示真实阶段并允许取消；数学超时仍是另一层独立限制。
+
+右侧检查器的结果使用源码默认值。需要改变默认预览时应编辑 `.kirin` 输入默认值；需要重复使用的组合应写成命名 `presets`。变换、求导、求解、扫描和网格目前使用相应 CLI 命令；多方案比较保留在共享计算服务层。这些高级操作没有在浏览器中复制成一组通用参数表单。
+
+### 与 Agent 一起创作
+
+保持 `kt web` 打开的同时，可以让本地 Agent 直接创建或修改工作区中的
+`entries/**/*.kirin`。Agent 不需要操作浏览器，也不需要通过 Kirin Tor CLI 写文档；工作台会自动发现新
+文档，并在当前缓冲区没有未保存修改时重新加载源码和派生预览。界面只显示最终文档、诊断与结果，
+不会显示 Agent 的提示词、操作过程、终端或 CLI 输出。
+
+这是一种以 `.kirin` 文件为中介的协作，不是共享光标或隐藏的 Agent 状态。Agent 看不到浏览器内尚未
+保存的草稿；若双方改到同一文档，工作台保留草稿并打开 base/draft/disk 冲突比较。Agent 直接修改多
+个文件也不属于 Save All 原子事务，期间出现的不完整源码会照常显示诊断，只有通过完整校验的模型才
+能计算。详细合同见[浏览器工作台规范](docs/web-workbench.md#external-agent-authoring)。
+
+常用编辑快捷键：
+
+| 操作 | 快捷键 |
+| --- | --- |
+| 保存全部 | `Mod+S` |
+| 补全 | `Ctrl+Space` |
+| 查找/替换 | `Mod+F` |
+| 跳到行 | `Mod+G` |
+| 文档符号大纲 | `Mod+Shift+O` |
+| 安全格式化 | `Mod+Shift+F` |
+| 转到定义 | `F12` 或 `Mod+单击` |
+| 查看定义与引用 | `Shift+F12` |
+| 安全重命名 | `F2` |
+| 工作区快速打开 | `Mod+K` 或 `Mod+P` |
+
+完整交互与权威边界见[浏览器工作台规范](docs/web-workbench.md)。
+
+## 语言和数学能力
+
+Kirin Tor source v2 使用一个 `entry` 文档模型和一致的逐项声明语法。正式 ID 保持 ASCII；中文别名只在声明它的条目中参与公式，显示标签只影响界面、解释和图表。跨文档引用、CLI 参数、运行记录和 Package 导出继续使用稳定的正式身份。
+
+当前内核支持：
+
+- 精确整数、有理数、十进制和科学计数法；
+- 数值与布尔输入、范围、整数限制、有限允许值和组合约束；
+- 用户声明的量纲、精确比例单位和可复用值域；
+- 字段、函数、输出、分组、参数方案、显示格式和版本化查表；
+- 封闭的可复用类型、具名对象和静态多层属性访问；
+- 有界 Process 状态、精确时间、事件 phase、连续 flow、动作 guard、冷却/充能等作者定义组件与固定策略；
+- 条件、分段、有限求和与连乘；
+- 有限离散分布、显式独立组合、条件化和有限重复；
+- Process 事件链形式的有界迭代，以及有限随机转移的 `reach` / `steady` / `cycle` 分析；
+- 化简、展开、因式分解、求导、单变量求解和最多八个变量的有限符号联立求解；
+- 一维扫描、双输入网格、SVG/PNG/CSV 图表以及可重放运行记录。
+
+完整语法写法见 [Kirin Tor source syntax v2](docs/kirin-syntax.md)；数学语义、安全边界和固定限制见[结构模型、表达式与安全边界](docs/schema-and-expressions.md)。
+
+## 社区 Package
+
+社区 Package 是独立维护、只含数据的 GitHub 仓库或本地开发目录。Kirin Tor 不执行其中的 Python、安装脚本、Git hook 或其他代码。
+
+公开仓库可添加 GitHub topic `kirin-tor-package`，从工作台的只读发现抽屉中被找到。Topic 只是社区自声明；发现不会安装内容，安装仍需用户明确指定来源与精确版本。
+
+创建并检查 Package：
+
+```bash
+kt package new my-community-package \
+  --name community.example \
+  --namespace community_example
+kt package check my-community-package
+```
+
+安装精确 GitHub 版本或本地不可变快照：
+
+```bash
+cd my-math
+kt package add example github:OWNER/REPOSITORY 1.0.0
+kt package add-path local_example ../my-community-package
+kt package list
+kt package verify
+```
+
+`kirin.packages.toml` 记录用户请求的直接依赖，`kirin.lock` 锁定完整依赖图、Git commit 和内容摘要，`.kirin/packages/` 是可删除并显式恢复的只读缓存。普通工作区加载不会隐式联网。
+
+完整协议见 [Kirin Tor community package protocol v1](docs/package-system-v1.md)。
+
+## Workbench Extension Plugins
+
+Workbench Plugin 可以为验证后的文档增加游戏化呈现器，也可以注册顶层页面、工作区工具、声明式命令和布局 Profile。插件不会改变 Kirin Tor 语法或数学结果；`.kirin`、验证器、Save All、Package 解析和运行记录仍由官方工作台控制。
+
+公开仓库可添加 GitHub topic `kirin-tor-plugin`，从工作台的只读发现抽屉中被找到。只有当前协议可解析的 manifest 会显示；发现不会下载、安装、批准、启用或执行插件。
+
+协议 v1 只安装作者明确选择的本地目录快照：
+
+```bash
+cd my-math
+kt plugin add-path talents /path/to/talent-plugin
+kt plugin list
+kt plugin verify
+kt web
+```
+
+插件清单、JavaScript、CSS、图片和其他静态文件全部进入内容摘要；安装时复制到 `.kirin/plugins/<SHA-256>/`，不会从可变源目录直接执行。`kirin.plugins.toml` 记录请求和启用状态，`kirin.plugins.lock` 锁定身份、版本与摘要，而可执行批准单独保存在工作区外的本机用户状态中。仅提交工作区配置不能批准陌生代码。
+
+插件页面运行在没有同源权限的沙箱 iframe 中，只能接收清单权限允许的 JSON 投影。v1 可代理定位源码以及对既有合法 target 的有界求值；插件无法读取会话令牌、宿主 DOM、文件系统、环境变量或网络，也不能调用 Save All 和 Package 变更。出现问题时可停用插件，或使用：
+
+```bash
+kt web --safe-mode
+```
+
+源码仓库提供了不含真实游戏数据的 `examples/plugins/fictional-talent-tree`，展示文档呈现器、页面、工具、命令与 Profile。完整清单、权限、frame 消息协议和限制见 [Workbench Extension Plugin protocol v1](docs/workbench-plugin-system-v1.md)。
+
+## 命令概览
+
+```text
+kt init DIRECTORY
+kt web [WORKSPACE|SOURCE.kirin] [--safe-mode]
+kt new entry ID [--template blank|data|model|semantics]
+kt list
+kt show ID
+kt explain TARGET
+kt check
+kt eval TARGET [--preset ENTRY.PRESET] [--set ENTRY.INPUT=VALUE]
+kt analyze ENTRY.ANALYSIS [--save-run ID] [--export-charts]
+kt simplify TARGET
+kt expand TARGET
+kt factor TARGET
+kt diff TARGET --var ENTRY.INPUT
+kt solve TARGET --var ENTRY.INPUT --equals VALUE
+kt solve-system --equation TARGET=VALUE --var ENTRY.INPUT
+kt scan --x ENTRY.INPUT --range START:END --points N --y TARGET
+kt grid --x ENTRY.INPUT --x-range START:END --x-points N \
+  --y ENTRY.INPUT --y-range START:END --y-points N --result TARGET
+kt plot [--config ENTRY_ID]
+kt replay RUN_ID
+kt package --help
+kt plugin --help
+```
+
+各命令的完整参数以 `kt COMMAND --help` 为准。输出文件默认限制在工作区内且不覆盖已有文件；扩大路径权限或覆盖文件必须显式请求。保存运行记录前，参与计算的源码必须已经保存。
+
+## 仓库示例
+
+`examples/虚构技能工作区` 只存在于源码仓库，不进入 wheel 或 source distribution。其数据完全虚构，只用于验证常见游戏公式形状：
+
+```bash
+cd "examples/虚构技能工作区"
+kt check
+kt eval combo.total --preset presets.baseline
+kt simplify combo.total --keep combo.crit
+kt diff combo.total --var combo.crit
+kt solve combo.total --var combo.crit --equals "3000 damage" --range "0:1"
+kt plot --config combo --force
+kt analyze rotation.replay_rotation
+kt analyze rotation.prove_rotation
+```
+
+关键结果包括 `2750 damage`、`2200*combo.crit + 2200`、导数 `2200 damage`、解 `4/11`，以及固定 Process 策略的精确轨迹与边界周期证明。这些都是测试数据，不代表任何真实游戏技能。
+
+## 能力边界
+
+Kirin Tor 可以直接处理作者给出的有限公式、有限分布，以及有明确 phase 和 fuel 的有界 Process 场景。Process Analysis 已支持精确有限随机路径、作者声明的条件或固定序列策略，以及 `run`、`compare`、确定性有界 `optimize`、`reach`、有限状态 `steady` 和 `cycle`。它不会从技能说明自动推导完整战斗循环。当前没有：
+
+- 优先级 APL、完整战斗时间线或随机采样；
+- 一般连续时间搜索的全局证明或带误差界全局求解；
+- 面向动态目标集合的公开建模承诺，或通用向量/矩阵语言；
+- 无界连续或离散全局优化器；
+- 积分、极限和完整通用数值根搜索。
+
+常见理论计算的适用范围和不可直接表达的问题见[游戏机制计算能力边界](docs/game-mechanics-capability-audit.md)。
+
+## 文档索引
+
+| 文档 | 职责 |
+| --- | --- |
+| [Kirin Tor source syntax v2](docs/kirin-syntax.md) | 表面语法、类型化属性、多层访问与 Process 写法 |
+| [结构模型、表达式与安全边界](docs/schema-and-expressions.md) | 解析后的数学语义、求值、安全和固定限制 |
+| [有界 Process 模型](docs/bounded-process-model.md) | 动态机制统一语义、fuel、分析器与证明边界 |
+| [有界 Process 纸面模型](docs/bounded-process-paper-models.md) | 六类机制的目标验证、Policy/Analysis 声明与当前可执行边界 |
+| [浏览器工作台规范](docs/web-workbench.md) | 界面、编辑状态、外部 Agent 协作、保存、冲突与权威边界 |
+| [Kirin Tor community package protocol v1](docs/package-system-v1.md) | Package manifest、解析、锁定、缓存和来源 |
+| [Workbench Extension Plugin protocol v1](docs/workbench-plugin-system-v1.md) | 沙箱 UI 插件、贡献点、权限、批准、锁定和安全模式 |
+| [游戏机制计算能力边界](docs/game-mechanics-capability-audit.md) | 已证明能力、需要外部等效模型的情况和明确非目标 |
+| [Changelog](CHANGELOG.md) | 版本历史、破坏性变更和未发布修改 |
+
+发生冲突时，以当前实现和测试为行为证据；表面语法以语法文档为准，数学与安全契约以结构模型文档为准，界面行为以工作台规范为准，Package 行为以 Package 协议为准。Changelog 只记录历史，不替代当前规范。

kirin_tor_cli-0.3.0rc3/README.md

@@ -0,0 +1,300 @@
+# Kirin Tor
+
+Kirin Tor 是一个游戏中立、文件驱动的结构化数学工作台，面向需要长期维护数据、公式、参数方案和图表的攻略与理论计算作者。
+
+工作区只有一种可编辑权威：`entries/**/*.kirin`。结果、图表、公式展开、诊断、关系图、索引、恢复缓存和导出文件都是源码的投影或产物，不会形成第二套计算定义。具体游戏的量纲、公式和数据由工作区或独立社区 Package 提供；Kirin Tor 核心不内置游戏、职业、技能或版本数据。
+
+Kirin Tor 不是脚本式战斗模拟器。内核只执行 source 明确声明且受 horizon、事件、决策、分支、实体和
+集合容量约束的 Process 事件场景；它不会补全完整 APL、Boss 时间轴或未声明规则，也不做隐式抽样。
+Process Analysis 已接入 CLI、浏览器工作台实时投影、多图导出和可重放运行记录。
+
+## 安装
+
+Kirin Tor 需要 Python 3.9 或更新版本。长期使用推荐先按
+[`uv` 官方说明](https://docs.astral.sh/uv/getting-started/installation/)安装 `uv`，再让它为 Kirin Tor
+维护独立环境。当前版本仍是预发布版，因此安装和升级时需要显式允许预发布版本：
+
+```bash
+uv tool install --prerelease allow kirin-tor-cli
+kt version
+kt web
+```
+
+以后升级仍使用同一独立环境，不需要进入源码目录或手动激活虚拟环境：
+
+```bash
+uv tool upgrade --prerelease allow kirin-tor-cli
+```
+
+正式版发布后，上述安装和升级命令可以省略 `--prerelease allow`。不再需要时可以完整移除：
+
+```bash
+uv tool uninstall kirin-tor-cli
+```
+
+也可以从 [GitHub Releases](https://github.com/Aaronlves/Kirin-Tor-Calc/releases) 下载 wheel，手动安装到自行管理的虚拟环境：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install /path/to/kirin_tor_cli-VERSION-py3-none-any.whl
+kt version
+```
+
+也可以直接安装当前源码：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install .
+kt --help
+```
+
+开发安装：
+
+```bash
+python -m pip install -e '.[dev]'
+pytest
+```
+
+## 快速开始
+
+创建并打开一个空的游戏中立工作区：
+
+```bash
+kt init my-math
+cd my-math
+kt web
+```
+
+浏览器工作台会显示三份只读教程：基础公式、参数方案与比较、扫描与图表。教程不是工作区文档；只有主动复制后，才会以普通未保存草稿进入校验和保存流程。
+
+也可以从命令行创建文档：
+
+```bash
+kt new entry basic_model --template model
+```
+
+一份最小而完整的 Kirin Tor source 如下：
+
+```text
+@kirin 2
+@entry basic_model "基础公式"
+
+input unit_price "单价": number[dimensionless] = 12 in 0..*
+input quantity "数量": number[dimensionless] = 5 in 0..100 integer
+input discount "折扣": probability = 10%
+
+field subtotal "小计": dimensionless = unit_price * quantity
+
+output total "折后总价": dimensionless = subtotal * (1 - discount)
+display total = number digits 2
+```
+
+保存为 `entries/basic_model.kirin` 后可以校验和计算：
+
+```bash
+kt check
+kt eval basic_model.total
+```
+
+结果为精确值 `54`。十进制先转换为精确有理数，不经过二进制浮点近似。
+
+## 浏览器工作台
+
+`kt web [WORKSPACE|SOURCE.kirin]` 启动只监听本机回环地址的浏览器工作台。服务使用随机会话令牌，不接受外部 Host、跨站 Origin 或远程监听；停止终端进程即可关闭，不存在后台守护程序或云端账户状态。
+
+工作台的主要能力包括：
+
+- 在中央 CodeMirror 编辑器中完成全部源码编辑；`Ctrl+Space` 提供 Kirin Tor 补全和中文结构片段。
+- 同时保留多个未保存草稿，按完整工作区校验，并通过 Save All 原子写入。
+- Agent 或其他本地工具直接改写 `.kirin` 后，干净文档与新文档会自动同步；未保存草稿不会被覆盖，也不会显示 CLI 或 Agent 操作记录。
+- 自动派生只读结果、静态图表、Process Analysis 多图、公式、诊断和局部关系；检查器不提供临时计算参数或参数方案填写字段。
+- 提供定义跳转、引用查找、符号大纲、签名提示、安全重命名、查找替换和安全空白格式化。
+- 提供工作区全文搜索、草稿式批量替换、保存前变更审查、只读 Git 摘要和外部冲突三方合并。
+- 支持文档路径移动、复制为新草稿，以及依赖安全的可恢复删除；这些文件操作不会改写源码中的 `@entry` ID 或数学语义。
+- 从已校验引用生成文档与成员关系图，并为图表和画布提供键盘可读的数据列表。
+- 通过独立本地进程执行长操作，显示真实阶段并允许取消；数学超时仍是另一层独立限制。
+
+右侧检查器的结果使用源码默认值。需要改变默认预览时应编辑 `.kirin` 输入默认值；需要重复使用的组合应写成命名 `presets`。变换、求导、求解、扫描和网格目前使用相应 CLI 命令；多方案比较保留在共享计算服务层。这些高级操作没有在浏览器中复制成一组通用参数表单。
+
+### 与 Agent 一起创作
+
+保持 `kt web` 打开的同时，可以让本地 Agent 直接创建或修改工作区中的
+`entries/**/*.kirin`。Agent 不需要操作浏览器，也不需要通过 Kirin Tor CLI 写文档；工作台会自动发现新
+文档，并在当前缓冲区没有未保存修改时重新加载源码和派生预览。界面只显示最终文档、诊断与结果，
+不会显示 Agent 的提示词、操作过程、终端或 CLI 输出。
+
+这是一种以 `.kirin` 文件为中介的协作，不是共享光标或隐藏的 Agent 状态。Agent 看不到浏览器内尚未
+保存的草稿；若双方改到同一文档，工作台保留草稿并打开 base/draft/disk 冲突比较。Agent 直接修改多
+个文件也不属于 Save All 原子事务，期间出现的不完整源码会照常显示诊断，只有通过完整校验的模型才
+能计算。详细合同见[浏览器工作台规范](docs/web-workbench.md#external-agent-authoring)。
+
+常用编辑快捷键：
+
+| 操作 | 快捷键 |
+| --- | --- |
+| 保存全部 | `Mod+S` |
+| 补全 | `Ctrl+Space` |
+| 查找/替换 | `Mod+F` |
+| 跳到行 | `Mod+G` |
+| 文档符号大纲 | `Mod+Shift+O` |
+| 安全格式化 | `Mod+Shift+F` |
+| 转到定义 | `F12` 或 `Mod+单击` |
+| 查看定义与引用 | `Shift+F12` |
+| 安全重命名 | `F2` |
+| 工作区快速打开 | `Mod+K` 或 `Mod+P` |
+
+完整交互与权威边界见[浏览器工作台规范](docs/web-workbench.md)。
+
+## 语言和数学能力
+
+Kirin Tor source v2 使用一个 `entry` 文档模型和一致的逐项声明语法。正式 ID 保持 ASCII；中文别名只在声明它的条目中参与公式，显示标签只影响界面、解释和图表。跨文档引用、CLI 参数、运行记录和 Package 导出继续使用稳定的正式身份。
+
+当前内核支持：
+
+- 精确整数、有理数、十进制和科学计数法；
+- 数值与布尔输入、范围、整数限制、有限允许值和组合约束；
+- 用户声明的量纲、精确比例单位和可复用值域；
+- 字段、函数、输出、分组、参数方案、显示格式和版本化查表；
+- 封闭的可复用类型、具名对象和静态多层属性访问；
+- 有界 Process 状态、精确时间、事件 phase、连续 flow、动作 guard、冷却/充能等作者定义组件与固定策略；
+- 条件、分段、有限求和与连乘；
+- 有限离散分布、显式独立组合、条件化和有限重复；
+- Process 事件链形式的有界迭代，以及有限随机转移的 `reach` / `steady` / `cycle` 分析；
+- 化简、展开、因式分解、求导、单变量求解和最多八个变量的有限符号联立求解；
+- 一维扫描、双输入网格、SVG/PNG/CSV 图表以及可重放运行记录。
+
+完整语法写法见 [Kirin Tor source syntax v2](docs/kirin-syntax.md)；数学语义、安全边界和固定限制见[结构模型、表达式与安全边界](docs/schema-and-expressions.md)。
+
+## 社区 Package
+
+社区 Package 是独立维护、只含数据的 GitHub 仓库或本地开发目录。Kirin Tor 不执行其中的 Python、安装脚本、Git hook 或其他代码。
+
+公开仓库可添加 GitHub topic `kirin-tor-package`，从工作台的只读发现抽屉中被找到。Topic 只是社区自声明；发现不会安装内容，安装仍需用户明确指定来源与精确版本。
+
+创建并检查 Package：
+
+```bash
+kt package new my-community-package \
+  --name community.example \
+  --namespace community_example
+kt package check my-community-package
+```
+
+安装精确 GitHub 版本或本地不可变快照：
+
+```bash
+cd my-math
+kt package add example github:OWNER/REPOSITORY 1.0.0
+kt package add-path local_example ../my-community-package
+kt package list
+kt package verify
+```
+
+`kirin.packages.toml` 记录用户请求的直接依赖，`kirin.lock` 锁定完整依赖图、Git commit 和内容摘要，`.kirin/packages/` 是可删除并显式恢复的只读缓存。普通工作区加载不会隐式联网。
+
+完整协议见 [Kirin Tor community package protocol v1](docs/package-system-v1.md)。
+
+## Workbench Extension Plugins
+
+Workbench Plugin 可以为验证后的文档增加游戏化呈现器，也可以注册顶层页面、工作区工具、声明式命令和布局 Profile。插件不会改变 Kirin Tor 语法或数学结果；`.kirin`、验证器、Save All、Package 解析和运行记录仍由官方工作台控制。
+
+公开仓库可添加 GitHub topic `kirin-tor-plugin`，从工作台的只读发现抽屉中被找到。只有当前协议可解析的 manifest 会显示；发现不会下载、安装、批准、启用或执行插件。
+
+协议 v1 只安装作者明确选择的本地目录快照：
+
+```bash
+cd my-math
+kt plugin add-path talents /path/to/talent-plugin
+kt plugin list
+kt plugin verify
+kt web
+```
+
+插件清单、JavaScript、CSS、图片和其他静态文件全部进入内容摘要；安装时复制到 `.kirin/plugins/<SHA-256>/`，不会从可变源目录直接执行。`kirin.plugins.toml` 记录请求和启用状态，`kirin.plugins.lock` 锁定身份、版本与摘要，而可执行批准单独保存在工作区外的本机用户状态中。仅提交工作区配置不能批准陌生代码。
+
+插件页面运行在没有同源权限的沙箱 iframe 中，只能接收清单权限允许的 JSON 投影。v1 可代理定位源码以及对既有合法 target 的有界求值；插件无法读取会话令牌、宿主 DOM、文件系统、环境变量或网络，也不能调用 Save All 和 Package 变更。出现问题时可停用插件，或使用：
+
+```bash
+kt web --safe-mode
+```
+
+源码仓库提供了不含真实游戏数据的 `examples/plugins/fictional-talent-tree`，展示文档呈现器、页面、工具、命令与 Profile。完整清单、权限、frame 消息协议和限制见 [Workbench Extension Plugin protocol v1](docs/workbench-plugin-system-v1.md)。
+
+## 命令概览
+
+```text
+kt init DIRECTORY
+kt web [WORKSPACE|SOURCE.kirin] [--safe-mode]
+kt new entry ID [--template blank|data|model|semantics]
+kt list
+kt show ID
+kt explain TARGET
+kt check
+kt eval TARGET [--preset ENTRY.PRESET] [--set ENTRY.INPUT=VALUE]
+kt analyze ENTRY.ANALYSIS [--save-run ID] [--export-charts]
+kt simplify TARGET
+kt expand TARGET
+kt factor TARGET
+kt diff TARGET --var ENTRY.INPUT
+kt solve TARGET --var ENTRY.INPUT --equals VALUE
+kt solve-system --equation TARGET=VALUE --var ENTRY.INPUT
+kt scan --x ENTRY.INPUT --range START:END --points N --y TARGET
+kt grid --x ENTRY.INPUT --x-range START:END --x-points N \
+  --y ENTRY.INPUT --y-range START:END --y-points N --result TARGET
+kt plot [--config ENTRY_ID]
+kt replay RUN_ID
+kt package --help
+kt plugin --help
+```
+
+各命令的完整参数以 `kt COMMAND --help` 为准。输出文件默认限制在工作区内且不覆盖已有文件；扩大路径权限或覆盖文件必须显式请求。保存运行记录前，参与计算的源码必须已经保存。
+
+## 仓库示例
+
+`examples/虚构技能工作区` 只存在于源码仓库，不进入 wheel 或 source distribution。其数据完全虚构，只用于验证常见游戏公式形状：
+
+```bash
+cd "examples/虚构技能工作区"
+kt check
+kt eval combo.total --preset presets.baseline
+kt simplify combo.total --keep combo.crit
+kt diff combo.total --var combo.crit
+kt solve combo.total --var combo.crit --equals "3000 damage" --range "0:1"
+kt plot --config combo --force
+kt analyze rotation.replay_rotation
+kt analyze rotation.prove_rotation
+```
+
+关键结果包括 `2750 damage`、`2200*combo.crit + 2200`、导数 `2200 damage`、解 `4/11`，以及固定 Process 策略的精确轨迹与边界周期证明。这些都是测试数据，不代表任何真实游戏技能。
+
+## 能力边界
+
+Kirin Tor 可以直接处理作者给出的有限公式、有限分布，以及有明确 phase 和 fuel 的有界 Process 场景。Process Analysis 已支持精确有限随机路径、作者声明的条件或固定序列策略，以及 `run`、`compare`、确定性有界 `optimize`、`reach`、有限状态 `steady` 和 `cycle`。它不会从技能说明自动推导完整战斗循环。当前没有：
+
+- 优先级 APL、完整战斗时间线或随机采样；
+- 一般连续时间搜索的全局证明或带误差界全局求解；
+- 面向动态目标集合的公开建模承诺，或通用向量/矩阵语言；
+- 无界连续或离散全局优化器；
+- 积分、极限和完整通用数值根搜索。
+
+常见理论计算的适用范围和不可直接表达的问题见[游戏机制计算能力边界](docs/game-mechanics-capability-audit.md)。
+
+## 文档索引
+
+| 文档 | 职责 |
+| --- | --- |
+| [Kirin Tor source syntax v2](docs/kirin-syntax.md) | 表面语法、类型化属性、多层访问与 Process 写法 |
+| [结构模型、表达式与安全边界](docs/schema-and-expressions.md) | 解析后的数学语义、求值、安全和固定限制 |
+| [有界 Process 模型](docs/bounded-process-model.md) | 动态机制统一语义、fuel、分析器与证明边界 |
+| [有界 Process 纸面模型](docs/bounded-process-paper-models.md) | 六类机制的目标验证、Policy/Analysis 声明与当前可执行边界 |
+| [浏览器工作台规范](docs/web-workbench.md) | 界面、编辑状态、外部 Agent 协作、保存、冲突与权威边界 |
+| [Kirin Tor community package protocol v1](docs/package-system-v1.md) | Package manifest、解析、锁定、缓存和来源 |
+| [Workbench Extension Plugin protocol v1](docs/workbench-plugin-system-v1.md) | 沙箱 UI 插件、贡献点、权限、批准、锁定和安全模式 |
+| [游戏机制计算能力边界](docs/game-mechanics-capability-audit.md) | 已证明能力、需要外部等效模型的情况和明确非目标 |
+| [Changelog](CHANGELOG.md) | 版本历史、破坏性变更和未发布修改 |
+
+发生冲突时，以当前实现和测试为行为证据；表面语法以语法文档为准，数学与安全契约以结构模型文档为准，界面行为以工作台规范为准，Package 行为以 Package 协议为准。Changelog 只记录历史，不替代当前规范。