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:
@@ -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 {
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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]
|
||||
}
|
||||
|
||||
@@ -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"},
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user