From bb8bc6dff9411e3a1a000b26eca47b08258e265b Mon Sep 17 00:00:00 2001 From: csh Date: Mon, 13 Jul 2026 15:26:25 +0800 Subject: [PATCH] :recycle: refactor(tsl): decouple skill routing from static docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 删除静态文档中对 tsl-syntax-reference / tsl-api-reference 的导航路由， 改由运行时按需自动触发；语法/API 事实的所有权与 fail-closed 约束 只保留在 rulesets/tsl/index.md 这一唯一权威载体。 - docs/tsl/index.md：删 4 行 skill 路由及重复的所有权/fail-closed 段，回归纯分流 - docs/tsl/modules/index.md：删 API 路由及指向已删 syntax 的 3 处回跳 - docs/index.md：删 skill 导航行及 2 条指向不存在文件的死 catalog 链 - docs/tsl/syntax/index.md：删除旧路径兼容 stub，不再保留任何兼容 - rulesets/tsl/index.md：删首跳 2 条 skill 导航，保留事实边界与 Fail closed - 同步修正相关测试断言 Co-Authored-By: Claude Fable 5 --- docs/index.md | 3 --- docs/tsl/index.md | 4 ---- docs/tsl/modules/index.md | 12 ++++-------- docs/tsl/syntax/index.md | 5 ----- rulesets/tsl/index.md | 2 -- test/cli/test_playbook_cli.py | 13 ------------- test/test_tsl_syntax_reference_skill.py | 15 --------------- 7 files changed, 4 insertions(+), 50 deletions(-) delete mode 100644 docs/tsl/syntax/index.md diff --git a/docs/index.md b/docs/index.md index 6fb61eb2..d394af78 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,10 +12,7 @@ - TSL 总入口（先判断主问题属于哪一层）：`tsl/index.md` - 代码风格：`tsl/code_style.md` - 命名规范：`tsl/naming.md` -- 语法手册（只处理“语言怎么写”）：[tsl-syntax-reference Skill](../skills/tsl-syntax-reference/SKILL.md) - 模块与集成入口（pyTSL、微信消息、回测框架）：`tsl/modules/index.md` -- 金融函数事实：`tsl/reference/catalog/datawarehouse.md` -- 函数检索入口（模块目录位于 `tsl/reference/catalog/`）：`tsl/reference/index.md` - 工具链与验证命令（模板）：`tsl/toolchain.md` ## C++（cpp） diff --git a/docs/tsl/index.md b/docs/tsl/index.md index 49897ddb..53c6b0f7 100644 --- a/docs/tsl/index.md +++ b/docs/tsl/index.md @@ -8,9 +8,5 @@ | 任务信号 | 入口 | 阻断条件 | | ---------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------- | -| 要生成或编写 TSL 代码、先定文件模型与起手骨架 | [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md) | 不写代码，只查语法、函数或命名事实 | -| 查语法写法、语言规则、排查语法错误 | [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md) | 要找的是函数，不是语法 | -| 取金融数据：行情、财务、板块、选股 | 使用 [tsl-api-reference Skill](../../skills/tsl-api-reference/SKILL.md) | 不是取数，是语法或语言规则 | -| 查 API/函数的名字、参数、返回值 | 使用 [tsl-api-reference Skill](../../skills/tsl-api-reference/SKILL.md) | 要查的是语法，不是 API 事实 | | 命名与代码风格：变量、函数、类型、文件取名，注释与代码组织 | 取名看 [naming.md](naming.md)；注释与组织看 [code_style.md](code_style.md) | 要查的是语法或函数事实 | | 具体模块能力：Python 调 TSL、策略回测、微信通知/告警 | [modules/index.md](modules/index.md) | 只是纯语法或普通取数 | diff --git a/docs/tsl/modules/index.md b/docs/tsl/modules/index.md index cf1f5513..42cc1f09 100644 --- a/docs/tsl/modules/index.md +++ b/docs/tsl/modules/index.md @@ -1,9 +1,11 @@ # 模块入口 -遇到不确定时：[pytsl_api.md](pytsl_api.md)、[tsbacktesting.md](tsbacktesting.md)、[wechat_message.md](wechat_message.md)、`tsl-api-reference`、项目自身文档、`scripts/*` 入口脚本、CI 配置 +遇到不确定时：[pytsl_api.md](pytsl_api.md)、[tsbacktesting.md](tsbacktesting.md)、[wechat_message.md](wechat_message.md)、项目自身文档、`scripts/*` 入口脚本、CI 配置 本页只负责把“现成模块、外部集成和模块 API”任务路由到正确事实页。目标页是模块 API 事实页时，智能体可以继续使用该页的签名、参数表、返回值和代码骨架；本页自身不生成代码。 +金融函数与通用函数库的名称、签名、参数和返回值由 `tsl-api-reference` skill 唯一拥有、按需自动触发，本页不再为其提供路由入口。 + ## 智能体模块路由规则 - 先判断任务是否属于模块 API、业务流程、通用语法、通用函数库或项目执行上下文。 @@ -19,9 +21,6 @@ | 2 | 用 Python 执行 TSL、调用服务器 TSL 函数、查行情、批量取数、异步取数 | [pytsl_api.md](pytsl_api.md) | 使用 pyTSL 类、函数、参数和返回结构 | | 3 | 发送微信通知、微信告警、微信模板消息、查询微信消息发送状态 | [wechat_message.md](wechat_message.md) | 使用微信消息接口、模板字段和展示规则 | | 4 | 写策略回测框架、组合回测、读取回测资产/持仓/交易/绩效结果 | [tsbacktesting.md](tsbacktesting.md) | 使用 `TSBackTesting` 对象模型、成员变量和查询接口 | -| 5 | 查询行情、财务、板块、选股等金融函数 | 使用 `tsl-api-reference` skill 关键词查 API | 使用数据仓库函数事实 | -| 6 | 询问 TSL 语言语法怎么写 | [../syntax/index.md](../syntax/index.md) | 回到语法主线 | -| 7 | 查询通用函数库函数签名、参数或返回值 | 使用 `tsl-api-reference` skill：已知名走 `--name`，未知名走 `--kw` | 回到 API reference 检索 | ## 模块页职责 @@ -33,7 +32,7 @@ ## 冲突处理 -- Python 执行一段 TSL 或调用服务器函数时，先读 [pytsl_api.md](pytsl_api.md)；TSL 代码本身再按 [../syntax/index.md](../syntax/index.md) 或 `tsl-api-reference` 补充。 +- Python 执行一段 TSL 或调用服务器函数时，先读 [pytsl_api.md](pytsl_api.md)；TSL 语法由 `tsl-syntax-reference` skill 唯一拥有、按需自动触发。 - Python 调用回测脚本时，先读 [pytsl_api.md](pytsl_api.md) 确认执行方式，再读 [tsbacktesting.md](tsbacktesting.md) 确认回测框架写法。 - 回测框架、交易字段和结果接口优先读 [tsbacktesting.md](tsbacktesting.md)；策略信号、证券池、费用口径等项目事实必须来自用户需求或项目实际接口。 - 微信通知内容来自业务结果时，先用业务页确定内容，再用 [wechat_message.md](wechat_message.md) 组织模板字段。 @@ -46,7 +45,4 @@ | 我要用 Python 调 TSL / 查行情 / 批量取数 | [pytsl_api.md](pytsl_api.md) | | 我要发微信通知 / 告警 / 查询状态 | [wechat_message.md](wechat_message.md) | | 我要写 `TSBackTesting` 回测框架 | [tsbacktesting.md](tsbacktesting.md) | -| 我要查行情 / 财务 / 板块 / 选股函数 | 使用 `tsl-api-reference` skill | -| 我要确认 TSL 语法 | [../syntax/index.md](../syntax/index.md) | -| 我要查通用函数库 | 使用 `tsl-api-reference` skill | | 我要确认真实账号 / 服务地址 / 部署入口 / 脚本入口 | 项目自身文档、`scripts/*`、CI 配置 | diff --git a/docs/tsl/syntax/index.md b/docs/tsl/syntax/index.md deleted file mode 100644 index 1f81e25f..00000000 --- a/docs/tsl/syntax/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# TSL 语法入口已迁移 - -TSL/TSF 语法事实现由仓库内唯一事实源 [tsl-syntax-reference Skill](../../../skills/tsl-syntax-reference/SKILL.md) 管理。 - -本页仅为旧路径兼容入口，不保存语法规则或专题路由。独立部署时请安装 `tsl-syntax-reference` 后再处理 TSL/TSF 语法任务。 diff --git a/rulesets/tsl/index.md b/rulesets/tsl/index.md index 6d45bb3a..701f2f2d 100644 --- a/rulesets/tsl/index.md +++ b/rulesets/tsl/index.md @@ -10,8 +10,6 @@ ## 文档首跳 -- TSL/TSF 语法、文件模型、语言规则、代码编写/修改/审查/解释和语法错误：使用 `tsl-syntax-reference` skill。 -- API/函数名称、签名、参数、返回值和金融取数：使用 `tsl-api-reference` skill。 - 命名偏好：读取 `docs/tsl/naming.md`。 - 代码风格：读取 `docs/tsl/code_style.md`。 - 验证命令和工具链：读取 `docs/tsl/toolchain.md`、项目脚本或 CI。 diff --git a/test/cli/test_playbook_cli.py b/test/cli/test_playbook_cli.py index ce9e7f36..62f21905 100644 --- a/test/cli/test_playbook_cli.py +++ b/test/cli/test_playbook_cli.py @@ -243,21 +243,8 @@ langs = ["tsl"] self.assertEqual(result.returncode, 0) text = docs_index.read_text(encoding="utf-8") self.assertIn("`tsl/index.md`", text) - self.assertIn("tsl-syntax-reference", text) - self.assertIn("`tsl/reference/catalog/datawarehouse.md`", text) self.assertIn("`tsl/modules/index.md`", text) - self.assertIn("`tsl/reference/index.md`", text) self.assertNotIn("`tsl/syntax_book/index.md`", text) - self.assertTrue( - ( - root - / CUSTOM_DEPLOY_ROOT - / "docs" - / "tsl" - / "syntax" - / "index.md" - ).is_file() - ) def test_external_clone_requires_explicit_playbook_root(self): with tempfile.TemporaryDirectory() as tmp_dir: diff --git a/test/test_tsl_syntax_reference_skill.py b/test/test_tsl_syntax_reference_skill.py index 51540d00..8f8613b4 100644 --- a/test/test_tsl_syntax_reference_skill.py +++ b/test/test_tsl_syntax_reference_skill.py @@ -8,7 +8,6 @@ ROOT = Path(__file__).resolve().parents[1] SKILL_DIR = ROOT / "skills" / "tsl-syntax-reference" SKILL_FILE = SKILL_DIR / "SKILL.md" REFERENCES_DIR = SKILL_DIR / "references" -COMPATIBILITY_INDEX = ROOT / "docs" / "tsl" / "syntax" / "index.md" RULESET_FILE = ROOT / "rulesets" / "tsl" / "index.md" LOOKUP_SCRIPT = SKILL_DIR / "scripts" / "lookup.py" @@ -188,18 +187,6 @@ class TslSyntaxReferenceSkillStructureTest(unittest.TestCase): actual = {path.name for path in SKILL_DIR.rglob("*")} self.assertTrue(forbidden.isdisjoint(actual), forbidden & actual) - def test_compatibility_index_contains_no_syntax_facts(self) -> None: - text = read_text(COMPATIBILITY_INDEX) - self.assertIn("../../../skills/tsl-syntax-reference/SKILL.md", text) - for forbidden in ( - "```", - "代码块身份", - "01_quickstart.md", - "02_core_model.md", - "| 任务", - ): - self.assertNotIn(forbidden, text) - def test_ruleset_file_remains_tsl_router(self) -> None: self.assertTrue(RULESET_FILE.is_file()) text = read_text(RULESET_FILE) @@ -240,10 +227,8 @@ class TslSyntaxReferenceSkillStructureTest(unittest.TestCase): def test_static_docs_route_to_fact_owner(self) -> None: routes = { - ROOT / "docs" / "tsl" / "index.md": "../../skills/tsl-syntax-reference/SKILL.md", ROOT / "docs" / "tsl" / "naming.md": "../../skills/tsl-syntax-reference/SKILL.md", ROOT / "docs" / "tsl" / "code_style.md": "../../skills/tsl-syntax-reference/SKILL.md", - ROOT / "docs" / "index.md": "../skills/tsl-syntax-reference/SKILL.md", } legacy_deep_link = re.compile(r"(?:docs/tsl/)?syntax/(?:0[1-9]|1[0-9]|2[0-4])_") for path, expected_link in routes.items():