refactor(cli): drop aiclient package; align AGENTS.md with mainstream

Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.

- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
  wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
  not env-gated): doc upload mode mutex, kb edit at-least-one,
  kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
  audience preamble + Build / Architecture / Command Structure /
  Testing / Code Style / Error Handling. Drops sections absent in
  surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
  and docs that pointed at docs/superpowers/ — that directory is
  local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
This commit is contained in:
nullkey
2026-05-15 02:16:45 +08:00
committed by lyingbug
parent a0dd989c81
commit f2e8e3f56c
111 changed files with 575 additions and 908 deletions
+1 -1
View File
@@ -20,7 +20,7 @@ func cachePath() (string, error) {
// LoadCache reads the cached Info. Returns (info, fresh, err).
//
// info == nil when no cache exists (err == nil)
// fresh == false 当 cache 不存在 / TTL 过期
// fresh == false when the cache is missing or TTL-expired
func LoadCache() (*Info, bool, error) {
p, err := cachePath()
if err != nil {
+1 -1
View File
@@ -28,7 +28,7 @@ func TestCache_RoundTrip(t *testing.T) {
t.Errorf("ServerVersion = %v, want %q", got, want.ServerVersion)
}
// 文件应在 $XDG_CACHE_HOME/weknora/server-info.yaml
// File should live at $XDG_CACHE_HOME/weknora/server-info.yaml
p := filepath.Join(dir, "weknora", "server-info.yaml")
if _, err := filepath.Abs(p); err != nil {
t.Errorf("path resolution: %v", err)
+13 -13
View File
@@ -10,9 +10,9 @@ import (
type Level int
const (
OK Level = iota // 兼容
SoftWarn // 服务器旧, 部分新功能不可用
HardError // 不兼容, 需升级 CLI 或 server
OK Level = iota // compatible
SoftWarn // server outdated; some new features may be unavailable
HardError // incompatible; CLI or server must be upgraded
)
func (l Level) String() string {
@@ -27,13 +27,13 @@ func (l Level) String() string {
return "unknown"
}
// Compat compares client/server version. v0.x 阶段允许漂移:
// Compat compares client/server versions. Cross-minor drift is allowed:
//
// 同 major, client minor ≤ server minor → OK
// 同 major, client minor > server minor → SoftWarn (server 旧, 部分新功能不可用)
// 不同 major → HardError
// 字符串 unparseable → OK (容错, 不阻塞)
// "(unknown)" / "" → OK (dev build / server 字段缺失)
// same major, client minor <= server minor -> OK
// same major, client minor > server minor -> SoftWarn (some new features may be unavailable)
// different major -> HardError
// unparseable string -> OK (fail-open, do not block)
// "(unknown)" / "" -> OK (dev build / server field missing)
func Compat(serverVer, cliVer string) (Level, string) {
sMaj, sMin, ok := parseSemver(serverVer)
if !ok {
@@ -44,7 +44,7 @@ func Compat(serverVer, cliVer string) (Level, string) {
return OK, ""
}
if sMaj != cMaj {
return HardError, fmt.Sprintf("incompatible: client %s vs server %s — upgrade required", cliVer, serverVer)
return HardError, fmt.Sprintf("incompatible: client %s vs server %s - upgrade required", cliVer, serverVer)
}
if cMin > sMin {
return SoftWarn, fmt.Sprintf("server is older (server %s, client %s); some new features may be unavailable", serverVer, cliVer)
@@ -56,14 +56,14 @@ func Compat(serverVer, cliVer string) (Level, string) {
// Accepts the leading "v" common in `git describe` output and Tencent/WeKnora
// tag conventions ("v0.1.0"), since both server `/system/info.version` and
// the CLI's own ldflags-injected build.Version may carry it.
// Returns ok=false 当字符串无法识别 (空 / "(unknown)" / 非数字)。
// Returns ok=false when the string is unrecognizable (empty / "(unknown)" / non-numeric).
func parseSemver(s string) (major, minor int, ok bool) {
if s == "" || s == "(unknown)" {
return 0, 0, false
}
// 接受 "v" 前缀:git describe + Tencent tag 都带 v
// Accept the "v" prefix; both `git describe` output and Tencent/WeKnora tags carry it.
s = strings.TrimPrefix(s, "v")
// 去掉 prerelease/build metadata
// Strip prerelease/build metadata.
if i := strings.IndexAny(s, "-+"); i >= 0 {
s = s[:i]
}
+2 -2
View File
@@ -19,9 +19,9 @@ func TestCompat(t *testing.T) {
{"client minor lower", "1.5.0", "1.2.0", compat.OK, ""},
{"client minor higher", "1.2.0", "1.5.0", compat.SoftWarn, "server is older"},
{"different major", "1.9.9", "2.0.0", compat.HardError, "incompatible"},
{"client unset", "1.2.3", "(unknown)", compat.OK, ""}, // dev build, 不报警
{"client unset", "1.2.3", "(unknown)", compat.OK, ""}, // dev build; no warning
{"server unset", "", "1.2.3", compat.OK, ""},
{"malformed server", "garbage", "1.2.3", compat.OK, ""}, // 不阻塞
{"malformed server", "garbage", "1.2.3", compat.OK, ""}, // fail-open
// "v" prefix tolerance (git describe + Tencent tag convention)
{"v-prefix both", "v1.2.0", "v1.5.0", compat.SoftWarn, "server is older"},
+2 -3
View File
@@ -1,5 +1,5 @@
// Package compat probes server `/system/info` and decides client-server
// version skew level. Used by `weknora doctor` 的 server_version 检查项。
// version skew level. Used by `weknora doctor`'s server_version check.
//
// 24h TTL state file cache, three-tier compat semantics
// (major-mismatch=hard / minor-mismatch=soft / equal=ok).
@@ -20,8 +20,7 @@ type Info struct {
ProbedAt time.Time `yaml:"probed_at"`
}
// ProbeService is the narrow SDK surface compat depends on (testability via
// fake; mirrors v0.0 service interface pattern).
// ProbeService is the narrow SDK surface compat depends on; tests inject a fake.
type ProbeService interface {
GetSystemInfo(ctx context.Context) (*sdk.SystemInfo, error)
}