复现包：xskill 0.6.0 on SpreadsheetBench (issue #48)

issue #48 的复现代码/补丁/产物备份（脚本、SkillOpt 集成补丁、晋升技能、状态报告、三方 eval 摘要）。所有 API key 已脱敏。仅作复现附件，非正式 release。

v0.5.2

xskill 0.5.2

主要改动 | Highlights

• feat(team): connect 默认直连、绕开公司代理 | client bypasses corporate proxy by default
  瘦客户端 httpx 由 trust_env=True 改为默认 trust_env=False，不再被 Windows 系统/注册表代理（如华为 SWG）劫持导致 502/504。新增 --use-proxy 逃生开关供"唯一出网靠代理"的场景。register 首连与后台同步两处都覆盖。
  The thin client no longer routes through the system/registry proxy (which caused 502/504 via corporate SWG). Added a --use-proxy escape hatch.

• feat(cli): registry list 支持 team 客户端视图 + 表头 | client-aware registry list + header
  客户端模式下从 detect_known_ecosystems + 上传游标现算：显示每个生态的真实源目录、已采集数、已上传数，不再永远空。
  On a team client, registry list now shows detected ecosystems with real source dirs and collected/uploaded counts.

• feat(pipeline): 过滤无效 trajectory 入流水线 | filter invalid trajectories before atom flow (#41)

• fix: 修正失效的 DeepSeek embedding 默认值 | replace invalid DeepSeek embedding defaults with working providers (#42)

• chore(deps): 移除未使用的 scikit-learn | drop unused scikit-learn
  连带去掉 scipy 等约 190MB 传递依赖；numpy 保留（embedding 归一化在用）。
  Removes scipy and friends (~190MB transitive); numpy stays.

• docs(readme): 全面视觉重设计为暖色海滩主题 | full visual redesign with warm beach theme

Install: pip install -U xskill==0.5.2 · PyPI: https://pypi.org/project/xskill/0.5.2/

v0.5.1

What's Changed

• docs: add architecture SVG diagram to README by @lintaojlu in #28
• docs: sync architecture diagram to README.zh-CN by @lintaojlu in #29
• fix(openclaw): type-check non-string text fields to prevent .strip() AttributeError by @kzclaw in #30
• feat(ecosystems): 新增 ngagent 适配器 | add ngagent (opencode enterprise fork) ecosystem support by @370025263 in #33
• feat(rate-limit): TokenBucket 双桶限流 + provider 兼容性 | TokenBucket dual-bucket rate limiter with provider compat by @370025263 in #36
• feat(team): 重连保持 client 身份不漂移 | preserve client identity across reconnect by @370025263 in #37
• feat(cluster): 禁 silent drop + partial-fail 重试 + per-atom 日志 | no silent drop, partial-fail retry, per-atom log by @370025263 in #38
• feat(install): 通用 copy+reverse_sync fallback + Windows junction 修复 | generic copy+reverse_sync chain + Windows junction fixes by @370025263 in #39
• feat(cli): 加 -v / --version 标志 | add -v / --version flag with single-source version by @370025263 in #40

New Contributors

• @lintaojlu made their first contribution in #28
• @kzclaw made their first contribution in #30

Full Changelog: v0.5.0...v0.5.1

v0.5.1a2

新功能 | New Features

• Rate-limit (TokenBucket): 双桶（RPM + TPM）限流器接入 LLMClient/agno_factory，避免有并发上限的模型套餐撞 429；默认 max_concurrent 30→4；OpenAI / DeepSeek / vLLM 三 provider 兼容；ADR-0001 写明 DIY 而非 litellm 的选型。Closes #31, #32. (PR #36)

• TokenBucket dual-bucket (RPM + TPM) rate limiter wired through LLMClient/agno_factory to avoid 429s on metered provider plans; max_concurrent default 30→4; provider compat tested across OpenAI / DeepSeek / vLLM; ADR-0001 documents the DIY choice over litellm.

• Team mode 重连身份保持: client 重连时把本地 team_client.json 里的 client_id 一起 POST 给 /register，server 三级续用（claimed_client_id → (hostname, label) 指纹 → 新发 uuid），消除重连即换身份导致 canary/历史归属/staging 断链的漏洞。(PR #37)

• Team-mode reconnect now preserves identity: client POSTs its existing client_id on /register; server resolves via 3-tier priority (claimed → fingerprint → new uuid). Fixes the regression where reconnect silently dropped canary bucket / trajectory history / user-staging branches.

• Cluster 政策修订 + 重试 + 去重 + 可观测性: 禁 silent drop（每个 atom 必 add_task_to_skill，含 ws=1）；partial-fail 重试 3 次封顶；调 cluster_agent 前 atom-id 去重，已落地的 atom 不再重投 LLM；per-atom atom → skill @ ws=N 日志 + drop 走 WARNING + 总结行三个数。(PR #38)

• Cluster policy revision: forbids silent drop (every atom must add_task_to_skill, including ws=1); partial-fail retry up to 3; atom_id-level dedup before re-clustering; per-atom log + summary line.

• 通用 install copy + reverse_sync 框架: install_dir 加 install-meta + _is_link_or_junction helper（Windows 查 FILE_ATTRIBUTE_REPARSE_POINT）+ auto_reset 钩子；reverse_sync_openclaw_dest 泛化为 reverse_sync_copy_dest；ngagent 改强制 copy + reverse_sync（Closes #34）；openclaw junction-aware rmtree（Closes #35）。(PR #39)

• Generic copy + reverse_sync install framework: install_dir gains install-meta + _is_link_or_junction helper + auto_reset hook; reverse_sync_openclaw_dest generalized to reverse_sync_copy_dest; ngagent forced to copy mode + reverse_sync (Closes #34); openclaw junction-aware rmtree (Closes #35).

备注 | Note

CI release workflow 的 publish step 受限于 pypa/gh-action-pypi-publish@release/v1 的 OIDC 要求，本次仍走本地手动 build + twine 发版。后续 PR 会修 release.yml（加 id-token: write 权限 + PyPI Trusted Publisher 配置）。

The CI release workflow's publish step still fails due to OIDC requirements in pypa/gh-action-pypi-publish@release/v1; published manually via local build + twine. A follow-up PR will fix release.yml (add id-token: write permission + PyPI Trusted Publisher setup).

v0.5.1a1

新功能 | New Features

• ngagent ecosystem 适配（opencode 企业分支）：新增 NGAGENT_SPEC / install_to_ngagent / install_all_to_ngagent，schema 与 opencode 一致复用 SqliteIngester，skill 装到 ~/.config/opencode/skills/ 而非 ~/.agents/skills/，可与 opencode 并存。详见 PR #33。
• Add ngagent (opencode enterprise fork) ecosystem support — same schema as opencode (shared SqliteIngester), but skills install to ~/.config/opencode/skills/. Coexists with opencode on the same host. See PR #33.

修复 | Fixes

• openclaw 适配器 对非字符串 text 字段做类型检查，避免对 thinking/自定义块调 .strip() AttributeError（PR #30）。
• team git_bundle 移除 4 处 bundle.close() 兼容老 dulwich（py3.9 解析到的版本）；Windows POSIX mode 测试跳过（PR #30 内含）。
• type-check non-string text fields in openclaw adapter to prevent .strip() AttributeError on thinking/custom blocks (PR #30).
• Drop bundle.close() calls for old-dulwich compat; skip POSIX-mode test on Windows (folded into PR #30).

备注 | Note

CI Release workflow 的 publish 步骤因为 pypa/gh-action-pypi-publish 新版本要求 OIDC 而失败，本次发版改用本地手动 build+twine 完成。需要修 .github/workflows/release.yml 加 id-token: write 权限，下个版本恢复 CI 发布路径。

v0.5.0 — Team mode + Cursor/OpenClaw + line-anchored atoms

中文版

v0.5.0 是 xskill 的首个 0.5 系列正式版（PyPI 上 0.4.2 之后跳过 alpha 直接 stable）。
本版本核心是 Team 模式（C/S 架构）落地、Cursor / OpenClaw 生态接入、线号锚定的 atom 切分，
以及把运行时对系统 git 的依赖彻底去掉。

重大特性

• Team 模式（多用户客户端-服务端）
  • 服务端独占 LLM key 与 git 主分支写权限；客户端只采集、脱敏、上传轨迹，再按 manifest 同步 skill。
  • xskill serve --server 起 server，xskill connect <host:port> --token <t> 接客户端。
  • 服务端按 client_id 做 canary 分桶（per-client 而非时间窗），manifest 由 80 ranked + 20 recommended slot 组成。
  • 客户端手改隔离在 user-staging/<client_id> 分支，只作为参考材料推回，不污染 main。
  • 传输用 git bundle，状态用 SQLite 持久化。
• Cursor 生态完整接入：采集 + skill install + Windows 适配 + 导入脚本。
• OpenClaw 生态接入：用 shutil.copytree 替代 symlink（OpenClaw 拒绝符号链接），并加 dest→source 回流桥让用户在 ~/.agents/skills/ 下的手改能被边吸收管线感知。
• 行号锚定 atom 切分：替换原先靠 LLM 瞎猜 char-offset 的方案，标记格式改成 [line:N]，atom 边界稳定可复现。
• Python 3.9 支持：补回 eval_type_backport 等运行时依赖，worker 线程显式装事件循环修复 agno 懒加载在 3.9 下的崩溃。

安全 / 隐私

• detect-secrets 脱敏：轨迹上传到 server 前先过 detect-secrets，把 API key、token、credential 等敏感内容 mask 掉。
• 客户端无 LLM API key、无 main 分支写权限——团队中 client 不可信。

体验改进

• recommended-20 改为用户画像质心推荐：基于客户端使用 profile 的 embedding 质心算最近邻，比之前的纯热度排序更贴用户。
• 运行时 dulwich 替代 subprocess git：pip install xskill 后无需系统 git，CI / Docker 镜像不再额外装。
• 首次启动自动生成 config 模板，附 example 和注释。
• opencode ingester 修复：正确读 part 表渲染真实对话内容，不再丢消息。

架构 / 内部重构

• 源码按职责拆子包：pipeline/、skill/、utils/、api/、ecosystems/、agents/、team/{server,client,shared}/。
• 移除 chat archive / SWE-bench sandbox / skill_eval / Evaluator 等历史子系统，砍掉死代码。
• 移除 web 面板遗留的 chat 端点，server 接口收敛到 /api/v1/team/* 与 skill 管理。

工程治理

• 添加 OSS 治理文件：issue / PR 模板、CONTRIBUTING、CODEOWNERS、SECURITY。
• README 重写为 outcome-first 风格，加 demo GIF 和 News 板块。
• 新增 Docker E2E：make e2e 覆盖 runtime_ecosystem_detect / runtime_openclaw_detect 两个场景，用 fake LLM 跑端到端。

已知限制

• 团队模式 server canary 决策仍按 pick_side(client_id, ...) 做，多个客户端 ID 经常重置时灰度分桶会失稳——计划在 0.5.x 加入 stable client_id 持久化。
• recommended-20 在用户使用 profile 还很稀疏（首日）时退化为热度排序。

---

English

v0.5.0 is the first stable release in the 0.5 line of xskill (jumping past the alpha series after 0.4.2 on PyPI).
The headline of this release is the Team mode (client-server architecture) landing, Cursor / OpenClaw ecosystem integrations, line-anchored atom splitting, and dropping the runtime dependency on the system git binary.

Major Features

• Team mode (multi-user client/server)
  • Server owns LLM keys and write access to main branches; clients only collect, redact, and upload trajectories, then sync skills per the server-issued manifest.
  • xskill serve --server starts the server; xskill connect <host:port> --token <t> registers a client.
  • Per-client canary bucketing via pick_side(client_id, ...) (deterministic per-client, no time-window rotation needed); manifests carry 80 ranked + 20 recommended slots.
  • Client user edits are isolated to user-staging/<client_id> branches, pushed back as reference material only — they never touch main.
  • Git bundle transport; SQLite-backed client registry and state.
• Cursor ecosystem full integration: collector + skill installer + Windows adaptation + import script.
• OpenClaw ecosystem integration: uses shutil.copytree instead of symlinks (OpenClaw rejects symlinks); a dest→source reverse-sync bridge lets user edits under ~/.agents/skills/ flow back into the absorb pipeline.
• Line-anchored atom splitting: replaces the old LLM-guessed char-offset scheme; markers are now [line:N], atom boundaries are stable and reproducible.
• Python 3.9 support: pulled in eval_type_backport, and worker threads now explicitly install an event loop to fix the agno lazy-import crash on 3.9.

Security / Privacy

• detect-secrets redaction: trajectories pass through detect-secrets before being uploaded to the server; API keys, tokens, and credentials are masked.
• Clients hold no LLM API key and have no write access to main — clients are untrusted by design.

UX Improvements

• recommended-20 now uses user-profile centroid recommendations: nearest-neighbor over the embedding centroid of each client's usage profile, instead of plain popularity ranking.
• Runtime git via dulwich, replacing all subprocess git calls: pip install xskill no longer needs the system git binary, simplifying CI / Docker images.
• First-run auto-generates a config template with examples and inline comments.
• opencode ingester fix: correctly reads the part table to render the real conversation content; no more dropped messages.

Architecture / Internal Refactor

• Source tree split into responsibility-scoped subpackages: pipeline/, skill/, utils/, api/, ecosystems/, agents/, team/{server,client,shared}/.
• Removed legacy chat archive, SWE-bench sandbox, skill_eval, and Evaluator subsystems — dead code is gone.
• Removed leftover chat endpoints from the old web panel; server surface area now lives under /api/v1/team/* and the skill management routes.

Engineering / Governance

• OSS governance files added: issue/PR templates, CONTRIBUTING, CODEOWNERS, SECURITY.
• README rewritten in outcome-first style with a demo GIF and a News section.
• New Docker E2E: make e2e covers runtime_ecosystem_detect and runtime_openclaw_detect, end-to-end against a fake LLM.

Known Limitations

• Server-side canary bucketing keys on client_id; when client IDs are reset frequently, bucket assignment becomes unstable. Persistent client_id is on the 0.5.x roadmap.
• recommended-20 degrades to popularity ranking on day one when the user-profile signal is still sparse.

---

Install

pip install xskill==0.5.0

Full Changelog

v0.4.2...v0.5.0 — 61 commits.