proxyctl 0.3.1__tar.gz → 0.3.3__tar.gz

{proxyctl-0.3.1 → proxyctl-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyctl
-Version: 0.3.1
+Version: 0.3.3
 Summary: Proxy configuration lifecycle management for macOS and Linux
 Project-URL: Homepage, https://github.com/crhan/proxyctl
 Project-URL: Issues, https://github.com/crhan/proxyctl/issues

{proxyctl-0.3.1 → proxyctl-0.3.3}/man/proxyctl.1

@@ -53,8 +53,10 @@ dns-lock / dns-unlock。
 .SH COMMANDS
 .SS 自描述（Agent 入口）
 .TP
-.B proxyctl agent-guide
+\fBproxyctl agent-guide\fR [\fB--list-sections\fR | \fB--section\fR \fINAME\fR]
 输出给 LLM 的运行时入门 markdown（能力地图 / 引导路径 / 决策树 / envelope 字段表 / 锁文件位置 / footgun）。
+v0.3.3 新增：\fB--list-sections\fR 列出所有 ASCII slug 形式的 section 名；
+\fB--section <name>\fR 只输出该 section（模糊匹配 + did-you-mean），agent 按需取小块。
 .TP
 \fBproxyctl explain\fR [\fITOPIC\fR]
 无参输出"想改 X 去哪？"速查表；带 topic 输出卡片。
@@ -74,7 +76,8 @@ supports_dry_run / needs_sudo / interactive / exit_codes / examples。
 .B proxyctl doctor [--json]
 极简 5 项健康打分：engine_up / port_listen / dns_ok / system_proxy_ok /
 connectivity_ok。\fB--json\fR 额外含 informational 字段：
-engine / mode / port / config_path / engine_config_path / lock_held / lock_path。
+engine / mode / port / config_path / engine_config_path / lock_held / lock_path /
+\fBhealthy\fR (v0.3.3 新增 bool，agent 不必再算 score==max)。
 .TP
 .B proxyctl help [\fICOMMAND\fR]
 顶层帮助 / 单命令完整说明。等价 \fBproxyctl --help\fR / \fBproxyctl <cmd> --help\fR。

{proxyctl-0.3.1 → proxyctl-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proxyctl"
-version = "0.3.1"
+version = "0.3.3"
 description = "Proxy configuration lifecycle management for macOS and Linux"
 readme = "README.md"
 requires-python = ">=3.10"

{proxyctl-0.3.1 → proxyctl-0.3.3}/src/proxyctl/__init__.py

@@ -1,3 +1,3 @@
 """proxyctl — Proxy configuration lifecycle management."""
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"

{proxyctl-0.3.1 → proxyctl-0.3.3}/src/proxyctl/audit.py

@@ -439,7 +439,7 @@ def cmd_audit(audit_days: int, api_base: str, api_secret: str, do_apply: bool):
     if candidates and not do_apply:
         print(f"\n执行 {BOLD}proxyctl audit apply{NC} 自动写入双 config")
 
-    _audit_emit(as_json, _sys, _real_stdout, collector)
+    _audit_emit(as_json, as_plain, _sys, _real_stdout, collector)
 
 
 def _audit_emit(as_json: bool, as_plain: bool, _sys, _real_stdout,

{proxyctl-0.3.1 → proxyctl-0.3.3}/src/proxyctl/check.py

@@ -944,7 +944,7 @@ def cmd_check(engine, api: str, api_secret: str,
              "detail": "skipped_in_structured_modes"},
             {"stage": "connectivity",
              "ok": all(c.get("ok") for c in conn) if conn else False,
-             "detail": ";".join(f"{c.get('target')}={c.get('http_code') or 'X'}"
+             "detail": ";".join(f"{c.get('name')}={'ok' if c.get('ok') else 'X'}"
                                  for c in conn)},
             {"stage": "outbound_ip",
              "ok": bool(out_ip),

{proxyctl-0.3.1 → proxyctl-0.3.3}/src/proxyctl/cli.py

@@ -1230,6 +1230,7 @@ def cmd_dns_unlock(config: dict):
         print(f"{YELLOW}dns-unlock 仅支持 macOS{NC}")
         return
     dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+    dns_lock_plist = f"/Library/LaunchDaemons/{dns_lock_label}.plist"
 
     r = run(["launchctl", "bootout", f"system/{dns_lock_label}"], sudo=True, capture=True)
     if r.returncode == 0:
@@ -1570,6 +1571,8 @@ def cmd_version_print() -> None:
                 "agents_md":               True,
                 "commands_schema":         True,
                 "doctor_extended":         True,
+                "doctor_healthy_field":    True,   # 0.3.3
+                "agent_guide_sections":    True,   # 0.3.3
                 "log_ndjson_v2":           True,
             },
         }
@@ -1723,7 +1726,7 @@ def _plan_mode(backend, target: str) -> list[dict]:
          "reversible": True,
          "side_effects": ["config-write"]},
         {"action": "subprocess",
-         "target": f"launchctl kickstart -k system/{backend.label}",
+         "target": f"launchctl kickstart -k {backend.label}",
          "summary": f"重启 launchd 服务以读取新 mode",
          "reversible": True, "requires_sudo": True,
          "side_effects": ["process"]},
@@ -1740,7 +1743,7 @@ def _plan_engine(backend, target: str) -> list[dict]:
         new_plist = f"/Library/LaunchDaemons/<{target}>.plist"
     return [
         {"action": "subprocess",
-         "target": f"launchctl bootout system/{backend.label}",
+         "target": f"launchctl bootout {backend.label}",
          "summary": f"停止当前引擎 {backend.name}",
          "reversible": True, "requires_sudo": True,
          "side_effects": ["process"]},

proxyctl-0.3.3/src/proxyctl/completion.py

@@ -0,0 +1,381 @@
+"""proxyctl completion — shell 补全脚本生成。
+
+支持 bash / zsh / fish。脚本从 COMMANDS_META + TOPICS 动态派生，
+0.3.x 起补全：
+
+  - 全局 flag: --help / --version / --json / --no-color / --quiet
+              / --dry-run / --plain
+  - explain <topic>          → topic 列表
+  - mode <tun|proxy>          → 模式
+  - engine <mihomo|singbox>   → 引擎
+  - config <path|get|set>     → 子命令
+  - audit <apply|N>           → 子命令 / 常用天数
+  - commands [--schema]        → 0.3.x schema 子模式
+  - agent-guide [--section <name> | --list-sections]   → 0.3.3 切片
+  - help <cmd>                → 顶层命令（与 <cmd> --help 同源）
+  - completion <bash|zsh|fish> → shell
+  - 写命令位置补 --dry-run；audit/check 位置补 --plain
+
+用法：
+    eval "$(proxyctl completion zsh)"
+    proxyctl completion bash > ~/.proxyctl.bash && echo 'source ~/.proxyctl.bash' >> ~/.bashrc
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+# 0.3.x：写命令支持 --dry-run（与 COMMANDS_META.supports_dry_run 同步）
+_DRY_RUN_CMDS = ("mode", "engine", "fix", "audit", "config",
+                 "daemon", "claude-proxy", "dns-lock", "dns-unlock")
+# 0.3.x：audit / check 支持 --plain
+_PLAIN_CMDS = ("audit", "check")
+# 0.3.x：commands 支持 --schema 子模式
+_SCHEMA_CMDS = ("commands",)
+# 0.3.3：agent-guide 支持 --section / --list-sections
+_AGENT_GUIDE_FLAGS = ("--section", "--list-sections")
+
+
+def _command_names() -> list:
+    from proxyctl.explain import COMMANDS_META
+    return [c["name"] for c in COMMANDS_META]
+
+
+def _topic_names() -> list:
+    from proxyctl.explain import TOPICS
+    return sorted(TOPICS.keys())
+
+
+def _gen_bash() -> str:
+    cmds = " ".join(_command_names())
+    topics = " ".join(_topic_names())
+    dry_run_cmds = " ".join(f'"{c}"' for c in _DRY_RUN_CMDS)
+    plain_cmds = " ".join(f'"{c}"' for c in _PLAIN_CMDS)
+    return f"""# proxyctl bash completion (0.3.x)
+_proxyctl_complete() {{
+    local cur prev cmds topics first
+    COMPREPLY=()
+    cur="${{COMP_WORDS[COMP_CWORD]}}"
+    prev="${{COMP_WORDS[COMP_CWORD-1]}}"
+    cmds="{cmds}"
+    topics="{topics}"
+    first="${{COMP_WORDS[1]}}"
+
+    # 第二个 token = 子命令
+    if [ ${{COMP_CWORD}} -eq 1 ]; then
+        COMPREPLY=( $(compgen -W "${{cmds}} help --help --version --json --plain --dry-run --no-color --quiet" -- "${{cur}}") )
+        return 0
+    fi
+
+    # help <cmd>（与 <cmd> --help 同源）
+    if [ "$first" = "help" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
+        COMPREPLY=( $(compgen -W "${{cmds}}" -- "${{cur}}") )
+        return 0
+    fi
+
+    # explain <topic>
+    if [ "$first" = "explain" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
+        COMPREPLY=( $(compgen -W "${{topics}}" -- "${{cur}}") )
+        return 0
+    fi
+
+    # mode <tun|proxy>
+    if [ "$first" = "mode" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
+        COMPREPLY=( $(compgen -W "tun proxy" -- "${{cur}}") )
+        return 0
+    fi
+
+    # engine <mihomo|singbox>
+    if [ "$first" = "engine" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
+        COMPREPLY=( $(compgen -W "mihomo singbox" -- "${{cur}}") )
+        return 0
+    fi
+
+    # config path|get|set
+    if [ "$first" = "config" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
+        COMPREPLY=( $(compgen -W "path get set" -- "${{cur}}") )
+        return 0
+    fi
+
+    # audit <apply|days>
+    if [ "$first" = "audit" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
+        COMPREPLY=( $(compgen -W "apply 1 3 7 30" -- "${{cur}}") )
+        return 0
+    fi
+
+    # commands --schema 子模式
+    if [ "$first" = "commands" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
+        COMPREPLY=( $(compgen -W "--schema --json" -- "${{cur}}") )
+        return 0
+    fi
+
+    # agent-guide --section / --list-sections
+    if [ "$first" = "agent-guide" ]; then
+        if [ "$prev" = "--section" ]; then
+            # 这里不知道实际 section list（运行时才有）；给个占位
+            COMPREPLY=( $(compgen -W "introduction onboarding capabilities envelope locks footgun" -- "${{cur}}") )
+            return 0
+        fi
+        COMPREPLY=( $(compgen -W "--section --list-sections --json" -- "${{cur}}") )
+        return 0
+    fi
+
+    # completion shell
+    if [ "$first" = "completion" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
+        COMPREPLY=( $(compgen -W "bash zsh fish" -- "${{cur}}") )
+        return 0
+    fi
+
+    # 在写命令的任意位置补 --dry-run
+    local dry_run_cmds=({dry_run_cmds})
+    for c in "${{dry_run_cmds[@]}}"; do
+        if [ "$first" = "$c" ]; then
+            COMPREPLY=( $(compgen -W "--dry-run --json --no-color --quiet --help" -- "${{cur}}") )
+            return 0
+        fi
+    done
+
+    # audit / check 加 --plain
+    local plain_cmds=({plain_cmds})
+    for c in "${{plain_cmds[@]}}"; do
+        if [ "$first" = "$c" ]; then
+            COMPREPLY=( $(compgen -W "--plain --json --dry-run --help" -- "${{cur}}") )
+            return 0
+        fi
+    done
+
+    # log 特有 flag
+    if [ "$first" = "log" ]; then
+        COMPREPLY=( $(compgen -W "--tail --no-follow --json --help" -- "${{cur}}") )
+        return 0
+    fi
+
+    # env 特有 flag
+    if [ "$first" = "env" ]; then
+        COMPREPLY=( $(compgen -W "--unset" -- "${{cur}}") )
+        return 0
+    fi
+
+    # 默认 flag 补全
+    COMPREPLY=( $(compgen -W "--help --json --plain --dry-run --no-color --quiet" -- "${{cur}}") )
+}}
+complete -F _proxyctl_complete proxyctl
+"""
+
+
+def _gen_zsh() -> str:
+    cmds = "\n".join(f"  '{name}:{summary}'" for name, summary in _zsh_pairs())
+    topics = " ".join(_topic_names())
+    return f"""#compdef proxyctl
+# proxyctl zsh completion (0.3.x)
+
+_proxyctl_topics() {{
+  local -a topics
+  topics=({topics})
+  _describe 'topic' topics
+}}
+
+_proxyctl_cmd_names() {{
+  local -a names
+  names=({' '.join(_command_names())})
+  _describe 'command' names
+}}
+
+_proxyctl() {{
+  local context state state_descr line
+  typeset -A opt_args
+
+  local -a cmds
+  cmds=(
+{cmds}
+    'help:顶层帮助 / 单命令帮助'
+  )
+
+  _arguments -C \\
+    '1: :->cmd' \\
+    '*: :->args' \\
+    '--help[显示帮助]' \\
+    '-h[显示帮助]' \\
+    '--version[显示版本（加 --json 暴露 supported_features）]' \\
+    '-v[显示版本]' \\
+    '--json[结构化 envelope v2 输出]' \\
+    '--plain[纯 TSV 输出（audit/check）；与 --json 互斥]' \\
+    '--dry-run[预演写命令；输出 data.plan]' \\
+    '--no-color[关闭 ANSI 颜色]' \\
+    '--quiet[安静模式]' \\
+    '-q[安静模式]'
+
+  case $state in
+    cmd) _describe 'command' cmds ;;
+    args)
+      case $words[2] in
+        help)        _proxyctl_cmd_names ;;
+        explain)     _proxyctl_topics ;;
+        mode)        _values 'mode' tun proxy ;;
+        engine)      _values 'engine' mihomo singbox ;;
+        config)      _values 'subcommand' path get set ;;
+        audit)       _values 'days_or_apply' apply 1 3 7 30 ;;
+        commands)    _values 'flag' --schema --json ;;
+        completion)  _values 'shell' bash zsh fish ;;
+        agent-guide)
+          if [[ "$words[$CURRENT-1]" == "--section" ]]; then
+            # 运行时取真实 section 名（fallback 常见值）
+            _values 'section' \\
+              introduction onboarding capabilities exclusions \\
+              concept-map paths exit-codes envelope decision-tree \\
+              non-interactive locks footgun self-discovery repo
+          else
+            _values 'flag' --section --list-sections --json
+          fi
+          ;;
+        log)         _values 'flag' --tail --no-follow --json ;;
+        env)         _values 'flag' --unset ;;
+      esac
+      ;;
+  esac
+}}
+
+compdef _proxyctl proxyctl
+"""
+
+
+def _zsh_pairs() -> list:
+    from proxyctl.explain import COMMANDS_META
+    out = []
+    for c in COMMANDS_META:
+        summary = c["summary"].replace("'", "'\\''")
+        out.append((c["name"], summary))
+    return out
+
+
+def _gen_fish() -> str:
+    from proxyctl.explain import COMMANDS_META
+    lines = ["# proxyctl fish completion (0.3.x)",
+             "complete -c proxyctl -l help -d '显示帮助'",
+             "complete -c proxyctl -l version -d '显示版本'",
+             "complete -c proxyctl -l json -d 'envelope v2 输出'",
+             "complete -c proxyctl -l plain -d 'TSV 输出（audit/check）'",
+             "complete -c proxyctl -l dry-run -d '预演写命令'",
+             "complete -c proxyctl -l no-color -d '关闭 ANSI'",
+             "complete -c proxyctl -l quiet -d '安静模式'",
+             ""]
+    # 全局子命令补全（不带子参数时）
+    for c in COMMANDS_META:
+        summary = c["summary"].replace("'", "")[:60]
+        lines.append(
+            f"complete -c proxyctl -n '__fish_use_subcommand' "
+            f"-a '{c['name']}' -d '{summary}'"
+        )
+    # help 也作为顶层子命令补
+    lines.append(
+        "complete -c proxyctl -n '__fish_use_subcommand' "
+        "-a 'help' -d '顶层/单命令帮助'"
+    )
+    # 子参数 / 子 flag
+    topics = " ".join(_topic_names())
+    lines.append("")
+    lines.append(
+        f"complete -c proxyctl -n '__fish_seen_subcommand_from explain' "
+        f"-a '{topics}'"
+    )
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from help' "
+        f"-a '{' '.join(_command_names())}'"
+    )
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from mode' "
+        "-a 'tun proxy'"
+    )
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from engine' "
+        "-a 'mihomo singbox'"
+    )
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from config' "
+        "-a 'path get set'"
+    )
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from completion' "
+        "-a 'bash zsh fish'"
+    )
+    # 0.3.x: 写命令补 --dry-run
+    for c in _DRY_RUN_CMDS:
+        lines.append(
+            f"complete -c proxyctl -n '__fish_seen_subcommand_from {c}' "
+            f"-l dry-run -d '预演（不真正执行）'"
+        )
+    # 0.3.x: audit/check 补 --plain
+    for c in _PLAIN_CMDS:
+        lines.append(
+            f"complete -c proxyctl -n '__fish_seen_subcommand_from {c}' "
+            f"-l plain -d 'TSV 输出'"
+        )
+    # 0.3.x: commands --schema
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from commands' "
+        "-l schema -d '输出 commands JSON Schema'"
+    )
+    # 0.3.3: agent-guide --section / --list-sections
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from agent-guide' "
+        "-l section -d '只输出指定 section'"
+    )
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from agent-guide' "
+        "-l list-sections -d '列出所有 section 名'"
+    )
+    # log / env 特有 flag
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from log' "
+        "-l tail -d '只取最后 N 行'"
+    )
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from log' "
+        "-l no-follow -d '一次性读取后返回'"
+    )
+    lines.append(
+        "complete -c proxyctl -n '__fish_seen_subcommand_from env' "
+        "-l unset -d '清除代理环境变量'"
+    )
+    return "\n".join(lines) + "\n"
+
+
+SHELLS = {"bash": _gen_bash, "zsh": _gen_zsh, "fish": _gen_fish}
+
+
+def cmd_completion(args: list) -> None:
+    """proxyctl completion [bash|zsh|fish]"""
+    from proxyctl import _io
+    try:
+        from proxyctl.explain import GLOBAL_FLAGS_REF as _gf
+        as_json = bool(_gf().get("json"))
+    except Exception:
+        as_json = False
+
+    if not args:
+        _io.fail("缺少 shell 参数",
+                 hint="proxyctl completion [bash|zsh|fish]",
+                 doc="agent", code=_io.USAGE, cmd="completion",
+                 as_json=as_json)
+        return
+
+    shell = args[0]
+    if shell not in SHELLS:
+        import difflib
+        suggest = difflib.get_close_matches(shell, list(SHELLS), n=1, cutoff=0.4)
+        hints = [f"支持: {', '.join(SHELLS)}"]
+        if suggest:
+            hints.insert(0, f"是否想要：{suggest[0]}？")
+        _io.fail(f"未知 shell：{shell}",
+                 hints=hints, doc="agent",
+                 code=_io.USAGE, cmd="completion",
+                 as_json=as_json)
+        return
+
+    script = SHELLS[shell]()
+    if as_json:
+        _io.emit_json(_io.envelope("completion",
+                                    data={"shell": shell, "script": script}))
+        return
+    print(script)

{proxyctl-0.3.1 → proxyctl-0.3.3}/src/proxyctl/explain.py

@@ -493,15 +493,143 @@ def _suggest(name: str, candidates: list) -> list:
 # ── 主入口 2: agent-guide ─────────────────────────────────────────────────
 
 def cmd_agent_guide(args: list, backend, config) -> None:
-    """proxyctl agent-guide [--json] — 给 LLM Agent 一份 ≤200 行的自描述文档。"""
+    """proxyctl agent-guide [--section <name>] [--list-sections] [--json]
+
+    无参 → 输出完整 markdown（≤300 行）。
+    `--list-sections` → 列出所有可用 section 名，agent 可挑一个取。
+    `--section <name>` → 只输出该 section 的 markdown（H2 标题下 + 直到下一个 H2）。
+    name 是大小写不敏感 + 空格容忍的模糊匹配（"envelope fields" / "envelope-fields"
+    / "Envelope 字段含义表" 都接受）。
+    """
     as_json = GLOBAL_FLAGS_REF().get("json", False)
+
+    # 解析 args
+    positional, flags = _io.extract_flags(
+        args, known={"--section": "value", "--list-sections": "bool"})
+
     text = _build_agent_guide(backend, config)
+    sections = _split_agent_guide_sections(text)
+    section_names = list(sections.keys())  # 保持原顺序
+
+    if flags.get("list_sections"):
+        if as_json:
+            emit_json(envelope("agent-guide", data={
+                "available_sections": section_names,
+                "section_count": len(section_names),
+            }))
+            return
+        print(f"{BOLD}可用 section（{len(section_names)} 个）：{NC}")
+        for s in section_names:
+            print(f"  {CYAN}{s}{NC}")
+        print(f"\n{DIM}用法：proxyctl agent-guide --section <name>{NC}")
+        return
+
+    requested = flags.get("section")
+    if requested:
+        match = _match_section(requested, section_names)
+        if match is None:
+            import difflib
+            suggest = difflib.get_close_matches(
+                requested, section_names, n=3, cutoff=0.3)
+            hints = [f"可用 section: {', '.join(section_names)}"]
+            if suggest:
+                hints.insert(0, f"是否想要：{suggest[0]}？")
+            _io.fail(f"未识别 section：{requested}",
+                     hints=hints, doc="agent",
+                     code=_io.USAGE, cmd="agent-guide")
+        chunk = sections[match]
+        if as_json:
+            emit_json(envelope("agent-guide", data={
+                "section": match,
+                "markdown": chunk,
+                "available_sections": section_names,
+            }))
+            return
+        print(chunk)
+        return
+
     if as_json:
-        emit_json(envelope("agent-guide", data={"markdown": text}))
+        emit_json(envelope("agent-guide", data={
+            "markdown": text,
+            "available_sections": section_names,
+        }))
         return
     print(text)
 
 
+def _split_agent_guide_sections(md: str) -> dict[str, str]:
+    """把 _build_agent_guide 输出的 markdown 按 H2 标题切分。
+
+    返回 OrderedDict 形式（python 3.7+ 普通 dict 即有序）：
+      {section_name: section_markdown_including_heading}
+
+    section_name 是 H2 标题去 emoji / 中文标点后的归一化版（lowercase + 空格连字符化），
+    便于 agent 用 ASCII 名稳定引用。
+    """
+    import re
+    lines = md.split("\n")
+    sections: dict[str, str] = {}
+    cur_name: str | None = None
+    cur_lines: list[str] = []
+    # 文档开头到第一个 H2 之前的内容 → "introduction"
+    intro_started = False
+    for ln in lines:
+        m = re.match(r"^##\s+(.+?)\s*$", ln)
+        if m:
+            # 收尾上一个 section
+            if cur_name is not None:
+                sections[cur_name] = "\n".join(cur_lines).rstrip() + "\n"
+            elif cur_lines:
+                # 文档开头部分作为 "introduction"
+                sections["introduction"] = "\n".join(cur_lines).rstrip() + "\n"
+            title = m.group(1).strip()
+            cur_name = _normalize_section_name(title)
+            cur_lines = [ln]
+        else:
+            cur_lines.append(ln)
+    if cur_name is not None:
+        sections[cur_name] = "\n".join(cur_lines).rstrip() + "\n"
+    elif cur_lines and not sections:
+        sections["introduction"] = "\n".join(cur_lines).rstrip() + "\n"
+    return sections
+
+
+def _normalize_section_name(title: str) -> str:
+    """H2 标题 → ASCII 友好的 section name（agent 引用稳定）。
+
+    约定：H2 推荐写成 ``## English Name — 中文标题``，取破折号（—/–/-）前
+    的英文段做 ID。这样 agent 引用的是稳定 ASCII slug，人类标题仍然中文友好。
+
+    映射规则：取破折号前内容（若有）→ 保留 ASCII 字母数字 → 空格合并 →
+    转连字符 → lowercase。全空回退 'section'。
+    """
+    import re
+    # 1. 取破折号前的部分（U+2014 — / U+2013 – / ASCII - 都接受）。
+    #    必须两边都有空格才算分隔符，避免误切 "Non-Interactive" / "Self-Discovery"
+    #    这类内部含 ASCII 连字符但无空格的英文短语。
+    parts = re.split(r"\s+[—–\-]\s+", title, maxsplit=1)
+    head = parts[0] if parts else title
+    # 2. 留下 ASCII 字母数字、空格、连字符
+    s = re.sub(r"[^A-Za-z0-9\s\-]", " ", head)
+    s = re.sub(r"\s+", " ", s).strip()
+    s = s.replace(" ", "-").lower()
+    # 3. 连续连字符合并 + 去边界
+    s = re.sub(r"-+", "-", s).strip("-")
+    return s or "section"
+
+
+def _match_section(requested: str, names: list[str]) -> str | None:
+    """模糊匹配：requested 可以是归一化后的 name、原始 H2 标题、或子串。"""
+    norm_req = _normalize_section_name(requested)
+    if norm_req in names:
+        return norm_req
+    # 子串匹配（防止 agent 拼 'envelope' 想找 'envelope-fields'）
+    candidates = [n for n in names if norm_req and norm_req in n]
+    if len(candidates) == 1:
+        return candidates[0]
+    return None
+
+
 def _build_agent_guide(backend, config) -> str:
     port = config.get("proxy_port", 7890)
     mcfg = backend.config_file
@@ -523,7 +651,7 @@ def _build_agent_guide(backend, config) -> str:
 > 本文档由 `proxyctl agent-guide` 在运行时输出，含当前 backend/路径/端口。
 > 仓库视角（开发/贡献协议）见仓库根 `AGENTS.md`。
 
-## Agent 第一次接入：6 步引导路径
+## Onboarding — Agent 第一次接入：6 步引导路径
 
 ```
 Step 1  proxyctl agent-guide              # 你正在看
@@ -537,7 +665,7 @@ Step 6  proxyctl explain <topic>          # 深入概念（topic 见下）
 
 调用任何写命令前先加 `--dry-run --json` 看 `data.plan`，确认无误再去掉。
 
-## 能做什么（按副作用三分类）
+## Capabilities — 能做什么（按副作用三分类）
 
 | 类别 | sudo | 命令 |
 |---|---|---|
@@ -549,7 +677,7 @@ Step 6  proxyctl explain <topic>          # 深入概念（topic 见下）
 
 完整精确表见 `proxyctl commands --json` 的 `side_effects` 与 `conditional_side_effects` 字段。
 
-## 不能做什么（去别处改）
+## Exclusions — 不能做什么（去别处改）
 
 - 添加 / 修改 / 删除分流规则 → 编辑 `{mcfg}` 的 `rules:` 段
 - 添加节点 / 改订阅 → 编辑 `{mcfg}` 的 `proxies:` / `proxy-providers:` 段
@@ -558,7 +686,7 @@ Step 6  proxyctl explain <topic>          # 深入概念（topic 见下）
 - 安装 mihomo / sing-box → `brew install mihomo` 等
 - 重启第三方应用 → 浏览器 / Slack / VSCode 需用户自己重启读 system proxy
 
-## 概念地图（"想改 X 去哪"）
+## Concept Map — "想改 X 去哪"
 
 | 想改 | 文件 | 段 / 字段 |
 |---|---|---|
@@ -571,7 +699,7 @@ Step 6  proxyctl explain <topic>          # 深入概念（topic 见下）
 更多：`proxyctl explain <topic>`，topic：
 {topics_list}
 
-## 关键路径（当前 backend = {backend.name}）
+## Paths — 关键路径（当前 backend = {backend.name}）
 
 - proxyctl 配置: `{pcfg}`
 - 引擎配置: `{mcfg}`
@@ -581,7 +709,7 @@ Step 6  proxyctl explain <topic>          # 深入概念（topic 见下）
 - 用户插件目录: `~/.config/proxyctl/plugins/*.py`
 - 锁文件目录: `{lock_dir}/.lock.{{system|config|daemon}}`
 
-## 退出码
+## Exit Codes — 退出码
 
 ```
 {exit_lines}
@@ -589,7 +717,7 @@ Step 6  proxyctl explain <topic>          # 深入概念（topic 见下）
 
 旧路径仍返回 1（GENERIC）。新错误路径使用分语义码。SIGINT → 130。
 
-## JSON envelope（schema v2）
+## Envelope — JSON envelope（schema v2）
 
 ```json
 {{
@@ -632,7 +760,7 @@ Step 6  proxyctl explain <topic>          # 深入概念（topic 见下）
 NDJSON 流式：`bench --json` 每节点一行 JSON + 末尾 envelope summary；
 `log --json` 每行一个 `{{file, line}}` 对象（非 envelope）。
 
-## 故障决策树（给 Agent 自动化）
+## Decision Tree — 故障决策树（给 Agent 自动化）
 
 1. `proxyctl doctor --json`  ← 最快，5 项布尔 + score（+ engine/mode/lock_path 信息字段）
 2. 如果 `engine_up=false` → `proxyctl start`
@@ -643,13 +771,13 @@ NDJSON 流式：`bench --json` 每节点一行 JSON + 末尾 envelope summary；
 7. 切网后 → `proxyctl recover`（不重启进程）
 8. 拿不到锁（exit=8 LOCKED）→ 见下方"锁文件位置 + 手动释放"
 
-## non-interactive 承诺
+## Non-Interactive — non-interactive 承诺
 
 proxyctl 在 stdin 非 TTY 时**不会**调用 `input()` 等阻塞读取。
 设置 `PROXYCTL_AGENT=1` 等价同时打开 `--json + --no-color + 非交互`，
 所有命令默认输出 envelope v2，写操作摘要打到 stderr。
 
-## 锁文件位置 + 手动释放
+## Locks — 锁文件位置 + 手动释放
 
 写操作（mode/engine/fix/audit apply/config set/daemon/dns-lock 等）通过
 `fcntl.flock` 保护，并发冲突返回 `LOCKED(8)`。
@@ -663,7 +791,7 @@ proxyctl 在 stdin 非 TTY 时**不会**调用 `input()` 等阻塞读取。
 
 LOCKED 错误的 `hints` 列表已包含具体锁路径。
 
-## footgun（提醒）
+## Footgun — footgun 提醒
 
 - `mode tun` 需要 sudo；macOS launchd 已自动 sudo prompt
 - `audit apply` 会写引擎 `rules:` 段；建议先 `proxyctl audit apply --dry-run`
@@ -672,7 +800,7 @@ LOCKED 错误的 `hints` 列表已包含具体锁路径。
 - 节点订阅由 mihomo `proxy-providers` 自管；proxyctl 不会刷新订阅
 - `--quiet` 仅压制非关键 stderr；envelope / error 仍输出
 
-## 自发现
+## Self-Discovery — 自发现
 
 - `proxyctl --version --json` — schema_version + supported_features 探测
 - `proxyctl commands --json` — 全部命令元数据
@@ -681,7 +809,7 @@ LOCKED 错误的 `hints` 列表已包含具体锁路径。
 - `proxyctl help <cmd>` — 单命令完整说明
 - `proxyctl doctor --json` — 健康基线
 
-## 仓库视角
+## Repo — 仓库视角
 
 如果你正在编辑 proxyctl 源码（而非调用安装好的 CLI），仓库根的
 `AGENTS.md` 含开发约定（DISPATCH 注册 / 错误路径 / 锁 / 提交规范）。
@@ -855,10 +983,14 @@ COMMANDS_META: list[dict] = [
      "needs_sudo": False, "interactive": False, "exit_codes": [0, 2],
      "examples": ["proxyctl explain", "proxyctl explain rules --json"]},
     {"name": "agent-guide", "group": "agent",
-     "summary": "给 LLM Agent 的入门 markdown（含能力边界、退出码、决策树）",
+     "summary": "给 LLM Agent 的入门 markdown（含能力边界、退出码、决策树）；"
+                "支持 --section <name> 按需取小块",
      "args": [], "supports_json": True, "side_effects": [],
-     "needs_sudo": False, "interactive": False, "exit_codes": [0],
-     "examples": ["proxyctl agent-guide", "proxyctl agent-guide --json"]},
+     "needs_sudo": False, "interactive": False, "exit_codes": [0, 2],
+     "examples": ["proxyctl agent-guide",
+                  "proxyctl agent-guide --list-sections",
+                  "proxyctl agent-guide --section envelope --json",
+                  "proxyctl agent-guide --json"]},
     {"name": "commands", "group": "agent",
      "summary": "所有命令的元数据（含 side_effects / needs_sudo / exit_codes）；"
                 "--schema 输出 JSON Schema",
@@ -1233,9 +1365,12 @@ def cmd_doctor(args: list, backend, config) -> None:
         held = []
     lock_path_map = _io.lock_paths()
 
+    healthy = (score == len(flags))
     data = {
         **flags,
-        "score": score, "max": len(flags), "hint": hint,
+        "score": score, "max": len(flags),
+        "healthy": healthy,        # 0.3.3：agent 不必自己算 score == max
+        "hint": hint,
         # informational fields (W15 in 0.3.0):
         "engine": backend.name,
         "mode": mode_str,
@@ -1245,7 +1380,6 @@ def cmd_doctor(args: list, backend, config) -> None:
         "lock_held": held,
         "lock_path": lock_path_map,
     }
-    healthy = (score == len(flags))
     code = OK if healthy else ENGINE_DOWN
 
     if as_json:
@@ -1342,5 +1476,12 @@ def GLOBAL_FLAGS_REF() -> dict:
 
 
 def set_global_flags(flags: dict) -> None:
+    """让 explain 模块 + _io 模块的 json 模式保持同步。
+
+    cli.main() 调一次即可；测试若想绕过 cli.main 直接调子命令，也应该用
+    这个 setter（而不是手工写 _GLOBAL_FLAGS），否则 _io.fail / _io.is_json_mode
+    会读到旧值，错误路径不输出 envelope。
+    """
     _GLOBAL_FLAGS.clear()
     _GLOBAL_FLAGS.update(flags)
+    _io.set_json_mode(bool(flags.get("json", False)))

{proxyctl-0.3.1 → proxyctl-0.3.3}/src/proxyctl/trace.py

@@ -575,11 +575,12 @@ def cmd_trace(raw_input: str, api: str, secret: str, config: dict = None):
     }
 
     t.join()
-    lines, conn_ok = connectivity_result[0]
+    lines, remote_ip = connectivity_result[0]
     for line in lines:
         print(line)
     collector["stages"]["connectivity"] = {
-        "ok": bool(conn_ok),
+        "ok": bool(remote_ip),
+        "remote_ip": remote_ip,
         "lines": [_strip_ansi(line) for line in lines],
     }
 
@@ -588,8 +589,7 @@ def cmd_trace(raw_input: str, api: str, secret: str, config: dict = None):
     if as_json:
         _sys.stdout = _real_stdout
         from proxyctl._io import emit_json, envelope, OK
-        emit_json(envelope("trace", data=collector,
-                           ok=bool(conn_ok), code=OK))
+        emit_json(envelope("trace", data=collector, ok=True, code=OK))
         _sys.exit(0)
 
 

proxyctl-0.3.1/src/proxyctl/completion.py

@@ -1,223 +0,0 @@
-"""proxyctl completion — shell 补全脚本生成。
-
-支持 bash / zsh / fish。脚本从 COMMANDS_META + TOPICS 动态派生。
-
-用法：
-    eval "$(proxyctl completion zsh)"   # 立即生效
-    proxyctl completion bash > ~/.proxyctl.bash && echo 'source ~/.proxyctl.bash' >> ~/.bashrc
-"""
-
-from __future__ import annotations
-
-import sys
-
-
-def _command_names() -> list:
-    from proxyctl.explain import COMMANDS_META
-    return [c["name"] for c in COMMANDS_META]
-
-
-def _topic_names() -> list:
-    from proxyctl.explain import TOPICS
-    return sorted(TOPICS.keys())
-
-
-def _gen_bash() -> str:
-    cmds = " ".join(_command_names())
-    topics = " ".join(_topic_names())
-    return f"""# proxyctl bash completion
-_proxyctl_complete() {{
-    local cur prev cmds topics
-    COMPREPLY=()
-    cur="${{COMP_WORDS[COMP_CWORD]}}"
-    prev="${{COMP_WORDS[COMP_CWORD-1]}}"
-    cmds="{cmds}"
-    topics="{topics}"
-
-    # 第二个 token = 子命令
-    if [ ${{COMP_CWORD}} -eq 1 ]; then
-        COMPREPLY=( $(compgen -W "${{cmds}} --help --version --json --no-color --quiet" -- "${{cur}}") )
-        return 0
-    fi
-
-    # explain <topic>
-    if [ "${{COMP_WORDS[1]}}" = "explain" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
-        COMPREPLY=( $(compgen -W "${{topics}}" -- "${{cur}}") )
-        return 0
-    fi
-
-    # mode <tun|proxy>
-    if [ "${{COMP_WORDS[1]}}" = "mode" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
-        COMPREPLY=( $(compgen -W "tun proxy" -- "${{cur}}") )
-        return 0
-    fi
-
-    # engine <mihomo|singbox>
-    if [ "${{COMP_WORDS[1]}}" = "engine" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
-        COMPREPLY=( $(compgen -W "mihomo singbox" -- "${{cur}}") )
-        return 0
-    fi
-
-    # config path|get|set
-    if [ "${{COMP_WORDS[1]}}" = "config" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
-        COMPREPLY=( $(compgen -W "path get set" -- "${{cur}}") )
-        return 0
-    fi
-
-    # audit apply 子参数
-    if [ "${{COMP_WORDS[1]}}" = "audit" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
-        COMPREPLY=( $(compgen -W "apply 1 3 7 30" -- "${{cur}}") )
-        return 0
-    fi
-
-    # completion shell
-    if [ "${{COMP_WORDS[1]}}" = "completion" ] && [ ${{COMP_CWORD}} -eq 2 ]; then
-        COMPREPLY=( $(compgen -W "bash zsh fish" -- "${{cur}}") )
-        return 0
-    fi
-
-    # 默认 flag 补全
-    COMPREPLY=( $(compgen -W "--help --json --no-color --quiet" -- "${{cur}}") )
-}}
-complete -F _proxyctl_complete proxyctl
-"""
-
-
-def _gen_zsh() -> str:
-    cmds = "\n".join(f"  '{name}:{summary}'" for name, summary in _zsh_pairs())
-    topics = " ".join(_topic_names())
-    return f"""#compdef proxyctl
-# proxyctl zsh completion
-
-_proxyctl_topics() {{
-  local -a topics
-  topics=({topics})
-  _describe 'topic' topics
-}}
-
-_proxyctl() {{
-  local context state state_descr line
-  typeset -A opt_args
-
-  local -a cmds
-  cmds=(
-{cmds}
-  )
-
-  _arguments -C \\
-    '1: :->cmd' \\
-    '*: :->args' \\
-    '--help[显示帮助]' \\
-    '--version[显示版本]' \\
-    '--json[结构化 JSON 输出]' \\
-    '--no-color[关闭 ANSI 颜色]' \\
-    '--quiet[安静模式]'
-
-  case $state in
-    cmd) _describe 'command' cmds ;;
-    args)
-      case $words[2] in
-        explain) _proxyctl_topics ;;
-        mode)    _values 'mode' tun proxy ;;
-        engine)  _values 'engine' mihomo singbox ;;
-        config)  _values 'subcommand' path get set ;;
-        audit)   _values 'days_or_apply' apply 1 3 7 30 ;;
-        completion) _values 'shell' bash zsh fish ;;
-      esac
-      ;;
-  esac
-}}
-
-compdef _proxyctl proxyctl
-"""
-
-
-def _zsh_pairs() -> list:
-    from proxyctl.explain import COMMANDS_META
-    out = []
-    for c in COMMANDS_META:
-        summary = c["summary"].replace("'", "'\\''")
-        out.append((c["name"], summary))
-    return out
-
-
-def _gen_fish() -> str:
-    from proxyctl.explain import COMMANDS_META
-    lines = ["# proxyctl fish completion",
-             "complete -c proxyctl -l help -d '显示帮助'",
-             "complete -c proxyctl -l version -d '显示版本'",
-             "complete -c proxyctl -l json -d '结构化 JSON 输出'",
-             "complete -c proxyctl -l no-color -d '关闭 ANSI'",
-             "complete -c proxyctl -l quiet -d '安静模式'",
-             ""]
-    # 全局子命令补全（不带子参数时）
-    for c in COMMANDS_META:
-        summary = c["summary"].replace("'", "")[:60]
-        lines.append(
-            f"complete -c proxyctl -n '__fish_use_subcommand' "
-            f"-a '{c['name']}' -d '{summary}'"
-        )
-    # explain topic
-    topics = " ".join(_topic_names())
-    lines.append("")
-    lines.append(
-        f"complete -c proxyctl -n '__fish_seen_subcommand_from explain' "
-        f"-a '{topics}'"
-    )
-    lines.append(
-        "complete -c proxyctl -n '__fish_seen_subcommand_from mode' "
-        "-a 'tun proxy'"
-    )
-    lines.append(
-        "complete -c proxyctl -n '__fish_seen_subcommand_from engine' "
-        "-a 'mihomo singbox'"
-    )
-    lines.append(
-        "complete -c proxyctl -n '__fish_seen_subcommand_from config' "
-        "-a 'path get set'"
-    )
-    lines.append(
-        "complete -c proxyctl -n '__fish_seen_subcommand_from completion' "
-        "-a 'bash zsh fish'"
-    )
-    return "\n".join(lines) + "\n"
-
-
-SHELLS = {"bash": _gen_bash, "zsh": _gen_zsh, "fish": _gen_fish}
-
-
-def cmd_completion(args: list) -> None:
-    """proxyctl completion [bash|zsh|fish]"""
-    from proxyctl import _io
-    try:
-        from proxyctl.explain import GLOBAL_FLAGS_REF as _gf
-        as_json = bool(_gf().get("json"))
-    except Exception:
-        as_json = False
-
-    if not args:
-        _io.fail("缺少 shell 参数",
-                 hint="proxyctl completion [bash|zsh|fish]",
-                 doc="agent", code=_io.USAGE, cmd="completion",
-                 as_json=as_json)
-        return
-
-    shell = args[0]
-    if shell not in SHELLS:
-        import difflib
-        suggest = difflib.get_close_matches(shell, list(SHELLS), n=1, cutoff=0.4)
-        hints = [f"支持: {', '.join(SHELLS)}"]
-        if suggest:
-            hints.insert(0, f"是否想要：{suggest[0]}？")
-        _io.fail(f"未知 shell：{shell}",
-                 hints=hints, doc="agent",
-                 code=_io.USAGE, cmd="completion",
-                 as_json=as_json)
-        return
-
-    script = SHELLS[shell]()
-    if as_json:
-        _io.emit_json(_io.envelope("completion",
-                                    data={"shell": shell, "script": script}))
-        return
-    print(script)