tytcli 0.2.0__py3-none-any.whl

tytcli/skill/references/wechat.md

@@ -0,0 +1,87 @@
+<!-- tytcli skill reference. Read this file only when the task needs it; -->
+<!-- SKILL.md is the routing surface and stays small on purpose.        -->
+
+# tytcli：公众号文章
+
+`wechat articles` / `wechat article` 的用法、精简输出与踩坑点。
+
+---
+
+## 公众号文章
+
+> ⚠️ **该模块并非在所有环境都已部署。**在未部署的环境上调用会得到 HTTP 404，
+> 错误的 `details.hint` 会说明“模块可能未部署”（`exit 1`）。那**不是**路由拼错，
+> 重试也不会成功——报错的 `error.details` 带 `env` 与 `base_url`，据此确认当前生效的环境。
+
+### 列文章
+
+```bash
+tytcli wechat articles                          # 全部文章，第一页 20 条
+tytcli wechat articles --page-size 5            # 每页 5 条（1–100）
+tytcli wechat articles --page 2                 # 第二页
+tytcli wechat articles --fake-id <ID>           # 只看某个公众号
+tytcli wechat articles --view SUBSCRIBED        # 我的订阅（或 FAVORITE 我的收藏）
+```
+
+**默认输出是精简索引**，每条只给五个字段：
+`title`、`nickname`、`summary`、`articleId`、`publishTime`。
+
+这是故意的：20 条原样输出有 66.8 KiB，而其中 74% 是 `cleanBody`（文章正文）——
+正文应该是详情命令的职责，不该在列表里重复 20 份。
+
+输出里的 `__tytcli_hint__` 会告诉你**本次服务端实际还返回了哪些字段**，以及怎么取：
+
+```bash
+tytcli wechat articles --fields title,digest,articleUrl   # 自选字段
+tytcli wechat articles --full                             # 全量原样（约 67 KiB）
+```
+
+`--fields` 与 `--full` 互斥。请求了服务端没返回的字段时，输出里会给出
+`unknown_fields` 和 `available_fields`，不会静默丢掉。
+
+### 看详情
+
+```bash
+tytcli wechat article --article-id <64位十六进制>
+```
+
+`articleId` 直接从列表输出里拿。详情**默认就是全量原样**（单篇约 14 KiB），含正文
+`body` 以及 `viewpoints`、`paragraphsJson`、`topicsJson`、`keywordsJson` 等分析字段。
+
+### 三个容易踩的坑
+
+1. **不要用标题定位文章。**服务端其实也接受 `identity`
+   （`{publishTime, account, title}` 三元组），但本命令**故意不提供**这个入口：
+   标题是长中文字符串且必须逐字节原样，实测尾部多一个空格就会得到
+   `文章不存在或已失效`。始终用 `articleId`。
+2. **`articleId` 和 `articleKey` 是同一个值，但不能互换。**详情接口只认
+   `articleId` 这个参数名；拿同一个值传 `articleKey` 会得到
+   `文章 identity 参数不完整或超长`。
+3. **`total` 不等于当页条数。**总数看 `data.total`，今日新增看 `data.todayCount`，
+   不要从 `records` 长度推断。
+
+## 典型管道
+
+先看今天有哪些文章（只要标题和时间）：
+
+```bash
+tytcli wechat articles --fields title,publishTime,nickname --page-size 20
+```
+
+拿第一篇文章的完整详情：
+
+```bash
+tytcli wechat articles --page-size 1 | jq -r '.data.records[0].articleId' | xargs -I{} tytcli wechat article --article-id {}
+```
+
+只要正文，不要分析字段：
+
+```bash
+tytcli wechat article --article-id <ID> | jq -r '.data.body'
+```
+
+先读 hint 再决定要不要加 `--fields`（适合不确定有哪些字段时）：
+
+```bash
+tytcli wechat articles --page-size 1 | jq -r '.__tytcli_hint__'
+```

tytcli/skill/references/whoami.md

@@ -0,0 +1,42 @@
+<!-- tytcli skill reference. Read this file only when the task needs it; -->
+<!-- SKILL.md is the routing surface and stays small on purpose.        -->
+
+# tytcli：whoami 与身份查询
+
+登录身份、权限菜单树，以及常用的 jq 组合。
+
+---
+
+## 常用组合
+
+只取身份摘要：
+
+```bash
+tytcli whoami | jq '.identity'
+```
+
+查看当前账号被授权了哪些功能模块：
+
+```bash
+tytcli whoami | jq -r '.data.Data.Menus[].MenuName'
+```
+
+列出全部可访问路由（含二级菜单）：
+
+```bash
+tytcli whoami | jq -r '.data.Data.Menus[] | .Url, ((.SubMenuList // [])[].Url)'
+```
+
+菜单名与路由的对应关系：
+
+```bash
+tytcli whoami | jq -r '.data.Data.Menus[] | .SubMenuList // [] | .[] | "\(.MenuName)\t\(.Url)"'
+```
+
+只用退出码判断登录态，不关心内容：
+
+```bash
+if tytcli whoami >/dev/null 2>&1; then echo "已登录"; else echo "未登录或凭证失效"; fi
+```
+
+`Menus` 里的是**前端路由**，可以用来了解这个账号被授权了哪些功能模块，但不能直接当成 API 路径使用。

tytcli/skill.py

@@ -0,0 +1,118 @@
+"""读取随包发布的 skill 文档。
+
+skill 在仓库里位于 ``skills/tytcli/``，开发期 pi 从那里发现它。hatchling 的
+``force-include``（见 ``pyproject.toml``）把同一批文件复制进 wheel 的
+``tytcli/skill/``，于是**已安装**的 tytcli 也能通过 ``tytcli help`` 打印自己的
+文档。本模块是唯一的读取者：``importlib.resources`` 在 wheel、zip 和 editable
+安装下都能工作。
+
+坚持单一来源很重要：文档若存在两处就必然漂移，而包内那一份才是用户真正看到的。
+"""
+
+from __future__ import annotations
+
+import importlib.resources as resources
+from pathlib import Path
+
+#: 顶层命令名 -> 记录它的参考文档。空键代表根命令，它的文档就是路由面本身。
+COMMAND_DOCS: dict[str, str] = {
+    "": "SKILL.md",
+    "whoami": "references/whoami.md",
+    "auth": "references/setup.md",
+    "config": "references/setup.md",
+    "upgrade": "references/selfupdate.md",
+    "wechat": "references/wechat.md",
+    "sentiment": "references/sentiment.md",
+    "roadshow": "references/roadshow.md",
+}
+
+#: 不是命令、但自己拥有一份参考文档的主题，所以即使没有 ``output`` 命令，
+#: ``tytcli help output`` 也能用。
+EXTRA_TOPICS: dict[str, str] = {
+    "output": "references/output-contract.md",
+    "setup": "references/setup.md",
+    "selfupdate": "references/selfupdate.md",
+}
+
+SKILL_FILENAME = "SKILL.md"
+
+
+def read_skill_doc(relative: str) -> str | None:
+    """返回一份随包文档；缺失时返回 ``None``。
+
+    ``relative`` 是 skill 目录内的路径，例如 ``SKILL.md`` 或
+    ``references/wechat.md``。文件缺失在这里**不算错误**：由调用方决定是降级
+    （某个命令还没有文档）还是大声失败（用户显式请求的主题）。
+
+    先读打包副本（``tytcli/skill/``，wheel 与 sdist 里都有）。打包副本不存在时
+    回退到仓库的 ``skills/tytcli/``——那正是 editable / 开发安装的情形：那里
+    force-include 映射没有跑过，若没有这层回退，``tytcli help`` 对用户可用、
+    对正在改文档的人却不可用。在 wheel 里打包副本永远优先，所以两者不可能对
+    "用户看到什么"产生分歧。
+    """
+    try:
+        traversable = resources.files("tytcli").joinpath("skill", *relative.split("/"))
+        return traversable.read_text(encoding="utf-8")
+    except (FileNotFoundError, ModuleNotFoundError, OSError):
+        pass
+
+    # editable 安装：src/tytcli/<本文件> -> 仓库根是 parents[2]。
+    repo_candidate = Path(__file__).resolve().parents[2] / "skills" / "tytcli" / relative
+    try:
+        return repo_candidate.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+
+def strip_frontmatter(text: str) -> str:
+    """去掉 YAML frontmatter——pi 需要它，终端不需要。
+
+    ``SKILL.md`` 以 ``---\\nname: …\\ndescription: …\\n---`` 开头。原样打印会让
+    输出以两行在 shell 里毫无意义的路由元数据开场。
+    """
+    if not text.startswith("---\n"):
+        return text
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return text
+    return text[end + len("\n---\n"):].lstrip("\n")
+
+
+def doc_for_topic(topic: str) -> tuple[str, str] | None:
+    """把 ``tytcli help <topic>`` 的参数解析成 ``(相对路径, 正文)``。
+
+    ``None`` 表示主题未知；命令会把它变成一个列出全部合法主题的用法错误。
+    """
+    relative = COMMAND_DOCS.get(topic) or EXTRA_TOPICS.get(topic)
+    if relative is None:
+        return None
+    text = read_skill_doc(relative)
+    if text is None:
+        return None
+    return relative, text
+
+
+def available_topics() -> list[str]:
+    """所有可接受的 ``help`` 主题：先命令，再额外主题。"""
+    ordered = [name for name in COMMAND_DOCS if name]
+    ordered += [name for name in EXTRA_TOPICS if name not in ordered]
+    return ordered
+
+
+def pointer_line(topic: str) -> str:
+    """追加到每个命令 ``--help`` 末尾的那一行指针。"""
+    if topic:
+        return f"完整文档：tytcli help {topic}"
+    return "完整文档：tytcli help"
+
+
+__all__ = [
+    "COMMAND_DOCS",
+    "EXTRA_TOPICS",
+    "SKILL_FILENAME",
+    "available_topics",
+    "doc_for_topic",
+    "pointer_line",
+    "read_skill_doc",
+    "strip_frontmatter",
+]