Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
feat(examples): Jira Cloud plugin with OAuth, dynamic options and a skill (#3730)
lyingbug4f5d475c3eeb
diff --git a/examples/plugins/jira/README.md b/examples/plugins/jira/README.mdnew file mode 100644index 000000000..9b4ff1d06--- /dev/null+++ b/examples/plugins/jira/README.md@@ -0,0 +1,59 @@+# Jira example plugin++Syncs the issues of selected Jira Cloud projects, with their comments, into a+knowledge base. It also ships a `jira-triage` skill that looks for duplicates,+related work and owners among the synced issues.++It is the fullest example plugin. It shows:++- a connector with incremental sync, checkpoints and deletions;+- an OAuth field (`x-oauth`): WeKnora runs Atlassian's consent flow and hands+ the plugin a fresh access token at every call;+- dynamic choices (`x-options`): the sites the account can reach and the+ site's issue types;+- form messages in the user's language (`call.Locale`);+- a skill in the package.++## Install++1. Build the package with `./package.sh` and install it under **System+ administration → Plugin management**.+2. To let workspaces sign in with their Atlassian accounts, register an app+ first. Without it, workspaces can still use an API token.+ 1. In the [Atlassian developer console](https://developer.atlassian.com/console/myapps/),+ create an OAuth 2.0 (3LO) app.+ 2. Under **Permissions → Jira API**, add `read:jira-work` and+ `read:jira-user`.+ 3. Under **Authorization**, set the callback URL to+ `<WeKnora address>/api/v1/plugin-oauth/callback`.+ 4. In the plugin's details in WeKnora, enter the app's client ID and+ secret.+3. Workspace admins switch the plugin on under **Settings → Plugins**, then+ add a **Jira** data source to a knowledge base.++## What is synced++Each issue becomes one Markdown document:++- **Title:** `<KEY> <summary>`.+- **Facts:** type, status, priority, resolution, assignee, reporter, labels,+ dates, parent, and a link.+- **Description**, converted from Atlassian Document Format.+- **Comments**, when enabled.++Attachments are not synced.++**Incremental syncs** fetch the issues updated since the newest one seen, in+the user's time zone, as JQL requires.++**Full syncs** also remove the documents of issues that were deleted, moved+out of the selected projects, or no longer match the filters.++## Test++```bash+go test ./examples/plugins/jira/+```++The tests run the plugin against a fake Jira Cloud site, both directly with+an API token and through the OAuth gateway.diff --git a/examples/plugins/jira/adf.go b/examples/plugins/jira/adf.gonew file mode 100644index 000000000..fceebbfdc--- /dev/null+++ b/examples/plugins/jira/adf.go@@ -0,0 +1,213 @@+package main++import (+ "encoding/json"+ "fmt"+ "strings"+)++// adfNode is a node of the Atlassian Document Format, the JSON Jira Cloud+// returns rich text in (descriptions, comments).+type adfNode struct {+ Type string `json:"type"`+ Text string `json:"text"`+ Attrs map[string]any `json:"attrs"`+ Marks []adfMark `json:"marks"`+ Content []adfNode `json:"content"`+}++type adfMark struct {+ Type string `json:"type"`+ Attrs map[string]any `json:"attrs"`+}++// adfToMarkdown renders ADF as Markdown. Unknown nodes keep their text, so+// nothing a new node type holds is lost from search. Plain strings (Jira's+// v2 API, old comments) pass through.+func adfToMarkdown(raw json.RawMessage) string {+ if len(raw) == 0 || string(raw) == "null" {+ return ""+ }+ var s string+ if json.Unmarshal(raw, &s) == nil {+ return strings.TrimSpace(s)+ }+ var doc adfNode+ if err := json.Unmarshal(raw, &doc); err != nil {+ return ""+ }+ var b strings.Builder+ blocks(&b, doc.Content, "")+ return strings.TrimSpace(b.String())+}++// blocks writes block nodes, each line prefixed with indent (list nesting,+// quotes).+func blocks(b *strings.Builder, nodes []adfNode, indent string) {+ for _, n := range nodes {+ switch n.Type {+ case "paragraph":+ line(b, indent, inline(n.Content))+ case "heading":+ level := 1+ if v, ok := n.Attrs["level"].(float64); ok && v >= 1 && v <= 6 {+ level = int(v)+ }+ line(b, indent, strings.Repeat("#", level)+" "+inline(n.Content))+ case "bulletList", "orderedList":+ for i, item := range n.Content {+ marker := "- "+ if n.Type == "orderedList" {+ marker = fmt.Sprintf("%d. ", i+1)+ }+ listItem(b, item, indent, marker)+ }+ b.WriteString("\n")+ case "codeBlock":+ lang, _ := n.Attrs["language"].(string)+ b.WriteString(indent + "```" + lang + "\n")+ for _, l := range strings.Split(plain(n.Content), "\n") {+ b.WriteString(indent + l + "\n")+ }+ b.WriteString(indent + "```\n\n")+ case "blockquote":+ blocks(b, n.Content, indent+"> ")+ case "rule":+ line(b, indent, "---")+ case "table":+ table(b, n, indent)+ case "panel", "expand", "nestedExpand", "layoutSection", "layoutColumn", "bodiedExtension":+ if title, _ := n.Attrs["title"].(string); title != "" {+ line(b, indent, "**"+title+"**")+ }+ blocks(b, n.Content, indent)+ case "mediaSingle", "mediaGroup", "media":+ // Attachments are not synced; say where one was.+ line(b, indent, "[attachment]")+ default:+ if len(n.Content) > 0 {+ blocks(b, n.Content, indent)+ } else if t := inline([]adfNode{n}); t != "" {+ line(b, indent, t)+ }+ }+ }+}++func line(b *strings.Builder, indent, text string) {+ b.WriteString(indent + text + "\n\n")+}++func listItem(b *strings.Builder, item adfNode, indent, marker string) {+ first := true+ for _, child := range item.Content {+ switch child.Type {+ case "paragraph":+ prefix := indent + strings.Repeat(" ", len(marker))+ if first {+ prefix = indent + marker+ }+ b.WriteString(prefix + inline(child.Content) + "\n")+ default:+ // Nested lists and other blocks go one level in.+ var sub strings.Builder+ blocks(&sub, []adfNode{child}, indent+" ")+ b.WriteString(strings.TrimRight(sub.String(), "\n") + "\n")+ }+ first = false+ }+}++func table(b *strings.Builder, n adfNode, indent string) {+ for i, row := range n.Content {+ cells := make([]string, 0, len(row.Content))+ for _, cell := range row.Content {+ var parts []string+ for _, p := range cell.Content {+ if t := strings.TrimSpace(inline(p.Content)); t != "" {+ parts = append(parts, t)+ }+ }+ cells = append(cells, strings.ReplaceAll(strings.Join(parts, " "), "|", "\\|"))+ }+ b.WriteString(indent + "| " + strings.Join(cells, " | ") + " |\n")+ if i == 0 {+ b.WriteString(indent + "|" + strings.Repeat(" --- |", len(cells)) + "\n")+ }+ }+ b.WriteString("\n")+}++// inline renders inline nodes with their marks.+func inline(nodes []adfNode) string {+ var b strings.Builder+ for _, n := range nodes {+ switch n.Type {+ case "text":+ b.WriteString(marked(n.Text, n.Marks))+ case "hardBreak":+ b.WriteString(" \n")+ case "mention":+ text, _ := n.Attrs["text"].(string)+ if !strings.HasPrefix(text, "@") {+ text = "@" + text+ }+ b.WriteString(text)+ case "emoji":+ text, _ := n.Attrs["text"].(string)+ if text == "" {+ text, _ = n.Attrs["shortName"].(string)+ }+ b.WriteString(text)+ case "inlineCard", "blockCard":+ u, _ := n.Attrs["url"].(string)+ b.WriteString(u)+ case "status":+ text, _ := n.Attrs["text"].(string)+ b.WriteString("[" + text + "]")+ case "date":+ if ts, ok := n.Attrs["timestamp"].(string); ok {+ b.WriteString(ts)+ }+ default:+ b.WriteString(inline(n.Content))+ }+ }+ return b.String()+}++func marked(text string, marks []adfMark) string {+ if strings.TrimSpace(text) == "" {+ return text+ }+ for _, m := range marks {+ switch m.Type {+ case "strong":+ text = "**" + text + "**"+ case "em":+ text = "*" + text + "*"+ case "strike":+ text = "~~" + text + "~~"+ case "code":+ text = "`" + text + "`"+ case "link":+ if href, _ := m.Attrs["href"].(string); href != "" {+ text = "[" + text + "](" + href + ")"+ }+ }+ }+ return text+}++// plain is the text of nodes without formatting (code blocks).+func plain(nodes []adfNode) string {+ var b strings.Builder+ for _, n := range nodes {+ if n.Type == "hardBreak" {+ b.WriteString("\n")+ }+ b.WriteString(n.Text)+ b.WriteString(plain(n.Content))+ }+ return b.String()+}diff --git a/examples/plugins/jira/client.go b/examples/plugins/jira/client.gonew file mode 100644index 000000000..830b7204d--- /dev/null+++ b/examples/plugins/jira/client.go@@ -0,0 +1,357 @@+package main++import (+ "bytes"+ "context"+ "encoding/base64"+ "encoding/json"+ "fmt"+ "io"+ "net/http"+ "net/url"+ "strconv"+ "strings"+ "time"++ "github.com/Tencent/WeKnora/pluginsdk/pluginapi"+)++// gatewayURL is Atlassian's API gateway, where OAuth tokens are used. Tests+// point it at a fake.+var gatewayURL = "https://api.atlassian.com"++// httpClient honors HTTPS_PROXY: a host plugin's traffic must go through the+// plugin host's egress proxy.+var httpClient = &http.Client{+ Timeout: 30 * time.Second,+ Transport: &http.Transport{Proxy: http.ProxyFromEnvironment},+}++// Credential fields, as the instance schema names them.+type credentials struct {+ Auth string `json:"auth"`+ Account string `json:"account"` // an OAuth access token by the time it reaches us+ Site string `json:"site"` // cloud ID+ BaseURL string `json:"base_url"`+ Email string `json:"email"`+ APIToken string `json:"api_token"`+}++// client calls one Jira Cloud site's REST API.+type client struct {+ api string // REST root: the site, or the gateway's /ex/jira/{cloudId}+ siteURL string // for links to issues+ auth string // Authorization header+}++// site is a Jira site an OAuth token can reach.+type site struct {+ ID string `json:"id"`+ URL string `json:"url"`+ Name string `json:"name"`+}++// accessibleSites lists the sites an OAuth token was granted.+func accessibleSites(ctx context.Context, token string) ([]site, error) {+ c := &client{api: gatewayURL, auth: "Bearer " + token}+ var sites []site+ err := c.do(ctx, http.MethodGet, "/oauth/token/accessible-resources", nil, &sites)+ return sites, err+}++// newClient checks the credentials and connects to the site they name.+// Problems with the form come back as invalid_config on its fields.+func newClient(ctx context.Context, cr credentials, locale string) (*client, error) {+ switch cr.Auth {+ case "", "oauth":+ if cr.Account == "" {+ return nil, pluginapi.InvalidConfig(say(locale, msgConnectAccount),+ map[string]string{"credentials.account": "required"})+ }+ if cr.Site == "" {+ return nil, pluginapi.InvalidConfig(say(locale, msgChooseSite),+ map[string]string{"credentials.site": "required"})+ }+ sites, err := accessibleSites(ctx, cr.Account)+ if err != nil {+ return nil, err+ }+ for _, s := range sites {+ if s.ID == cr.Site {+ return &client{+ api: gatewayURL + "/ex/jira/" + url.PathEscape(s.ID),+ siteURL: strings.TrimSuffix(s.URL, "/"),+ auth: "Bearer " + cr.Account,+ }, nil+ }+ }+ return nil, pluginapi.InvalidConfig(say(locale, msgSiteGone),+ map[string]string{"credentials.site": "not granted"})+ case "token":+ base := strings.TrimSuffix(strings.TrimSpace(cr.BaseURL), "/")+ fields := map[string]string{}+ if base == "" {+ fields["credentials.base_url"] = "required"+ }+ if cr.Email == "" {+ fields["credentials.email"] = "required"+ }+ if cr.APIToken == "" {+ fields["credentials.api_token"] = "required"+ }+ if len(fields) > 0 {+ return nil, pluginapi.InvalidConfig(say(locale, msgTokenFields), fields)+ }+ basic := cr.Email + ":" + cr.APIToken+ return &client{+ api: base, siteURL: base,+ auth: "Basic " + base64.StdEncoding.EncodeToString([]byte(basic)),+ }, nil+ default:+ return nil, pluginapi.InvalidConfig(say(locale, msgUnknownAuth),+ map[string]string{"credentials.auth": "enum"})+ }+}++// do sends one request and decodes a JSON answer. Jira's failures map to+// protocol errors: WeKnora retries unavailable and rate_limited, and shows+// unauthorized as broken credentials.+func (c *client) do(ctx context.Context, method, path string, body, out any) error {+ var rd io.Reader+ if body != nil {+ b, err := json.Marshal(body)+ if err != nil {+ return err+ }+ rd = bytes.NewReader(b)+ }+ req, err := http.NewRequestWithContext(ctx, method, c.api+path, rd)+ if err != nil {+ return err+ }+ req.Header.Set("Authorization", c.auth)+ req.Header.Set("Accept", "application/json")+ if body != nil {+ req.Header.Set("Content-Type", "application/json")+ }+ resp, err := httpClient.Do(req)+ if err != nil {+ return pluginapi.Errorf(pluginapi.CodeUnavailable, "jira: %v", err)+ }+ defer func() { _ = resp.Body.Close() }()+ data, err := io.ReadAll(io.LimitReader(resp.Body, 32<<20))+ if err != nil {+ return pluginapi.Errorf(pluginapi.CodeUnavailable, "jira: %v", err)+ }+ if resp.StatusCode >= 300 {+ return statusError(resp, data)+ }+ if out == nil {+ return nil+ }+ if err := json.Unmarshal(data, out); err != nil {+ return fmt.Errorf("jira %s: decode: %w", path, err)+ }+ return nil+}++func statusError(resp *http.Response, body []byte) error {+ msg := jiraMessage(body)+ switch {+ case resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden:+ return pluginapi.Errorf(+ pluginapi.CodeUnauthorized,+ "jira refused the credentials (%d): %s",+ resp.StatusCode,+ msg,+ )+ case resp.StatusCode == http.StatusTooManyRequests:+ e := pluginapi.Errorf(pluginapi.CodeRateLimited, "jira rate limit: %s", msg)+ if s, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil && s > 0 {+ e.Details = &pluginapi.ErrorDetails{RetryAfter: s}+ }+ return e+ case resp.StatusCode >= 500:+ return pluginapi.Errorf(pluginapi.CodeUnavailable, "jira %d: %s", resp.StatusCode, msg)+ case resp.StatusCode == http.StatusBadRequest:+ // Mostly a JQL filter Jira does not accept.+ return pluginapi.InvalidConfig("jira rejected the query: "+msg,+ map[string]string{"settings.jql": msg})+ default:+ return fmt.Errorf("jira %d: %s", resp.StatusCode, msg)+ }+}++// jiraMessage extracts Jira's error text ({"errorMessages": [...]}).+func jiraMessage(body []byte) string {+ var e struct {+ ErrorMessages []string `json:"errorMessages"`+ Errors map[string]string `json:"errors"`+ Message string `json:"message"`+ }+ if json.Unmarshal(body, &e) == nil {+ parts := append([]string{}, e.ErrorMessages...)+ for k, v := range e.Errors {+ parts = append(parts, k+": "+v)+ }+ if e.Message != "" {+ parts = append(parts, e.Message)+ }+ if len(parts) > 0 {+ return strings.Join(parts, "; ")+ }+ }+ s := strings.TrimSpace(string(body))+ if len(s) > 200 {+ s = s[:200]+ }+ return s+}++// myself is the signed-in user. Its time zone is the one JQL dates are in.+type myself struct {+ AccountID string `json:"accountId"`+ DisplayName string `json:"displayName"`+ TimeZone string `json:"timeZone"`+}++func (c *client) myself(ctx context.Context) (*myself, error) {+ var me myself+ if err := c.do(ctx, http.MethodGet, "/rest/api/3/myself", nil, &me); err != nil {+ return nil, err+ }+ return &me, nil+}++type project struct {+ ID string `json:"id"`+ Key string `json:"key"`+ Name string `json:"name"`+ Description string `json:"description"`+ Style string `json:"style"`+}++// projects lists every project the user can browse.+func (c *client) projects(ctx context.Context) ([]project, error) {+ var out []project+ for start := 0; ; {+ var page struct {+ Values []project `json:"values"`+ IsLast bool `json:"isLast"`+ }+ q := url.Values{"startAt": {strconv.Itoa(start)}, "maxResults": {"50"}, "orderBy": {"name"}}+ if err := c.do(ctx, http.MethodGet, "/rest/api/3/project/search?"+q.Encode(), nil, &page); err != nil {+ return nil, err+ }+ out = append(out, page.Values...)+ if page.IsLast || len(page.Values) == 0 {+ return out, nil+ }+ start += len(page.Values)+ }+}++type issueType struct {+ Name string `json:"name"`+ Subtask bool `json:"subtask"`+}++func (c *client) issueTypes(ctx context.Context) ([]issueType, error) {+ var out []issueType+ err := c.do(ctx, http.MethodGet, "/rest/api/3/issuetype", nil, &out)+ return out, err+}++// issue is the part of a Jira issue the connector turns into a document.+type issue struct {+ ID string `json:"id"`+ Key string `json:"key"`+ Fields struct {+ Summary string `json:"summary"`+ Description json.RawMessage `json:"description"`+ Status *named `json:"status"`+ IssueType *named `json:"issuetype"`+ Priority *named `json:"priority"`+ Resolution *named `json:"resolution"`+ Assignee *user `json:"assignee"`+ Reporter *user `json:"reporter"`+ Labels []string `json:"labels"`+ Created jiraTime `json:"created"`+ Updated jiraTime `json:"updated"`+ Project *project `json:"project"`+ Parent *struct {+ Key string `json:"key"`+ } `json:"parent"`+ Comment *struct {+ Comments []comment `json:"comments"`+ Total int `json:"total"`+ } `json:"comment"`+ } `json:"fields"`+}++type named struct {+ Name string `json:"name"`+}++type user struct {+ DisplayName string `json:"displayName"`+}++type comment struct {+ Author *user `json:"author"`+ Created jiraTime `json:"created"`+ Body json.RawMessage `json:"body"`+}++// jiraTime parses Jira's timestamps ("2026-09-26T10:04:05.123+0800").+type jiraTime struct{ time.Time }++func (t *jiraTime) UnmarshalJSON(b []byte) error {+ var s string+ if err := json.Unmarshal(b, &s); err != nil || s == "" {+ return nil+ }+ for _, layout := range []string{"2006-01-02T15:04:05.000-0700", time.RFC3339Nano} {+ if v, err := time.Parse(layout, s); err == nil {+ t.Time = v+ return nil+ }+ }+ return nil+}++var searchFields = []string{+ "summary", "description", "status", "issuetype", "priority", "resolution", "assignee", "reporter",+ "labels", "created", "updated", "project", "parent", "comment",+}++// search runs JQL a page at a time (the enhanced search API, which pages+// with a token). fn sees each page; returning an error stops the search.+func (c *client) search(ctx context.Context, jql string, withComments bool, fn func([]issue) error) error {+ fields := searchFields+ if !withComments {+ fields = fields[:len(fields)-1]+ }+ token := ""+ for {+ body := map[string]any{"jql": jql, "maxResults": 50, "fields": fields}+ if token != "" {+ body["nextPageToken"] = token+ }+ var page struct {+ Issues []issue `json:"issues"`+ NextPageToken string `json:"nextPageToken"`+ IsLast bool `json:"isLast"`+ }+ if err := c.do(ctx, http.MethodPost, "/rest/api/3/search/jql", body, &page); err != nil {+ return err+ }+ if err := fn(page.Issues); err != nil {+ return err+ }+ if page.IsLast || page.NextPageToken == "" || len(page.Issues) == 0 {+ return nil+ }+ token = page.NextPageToken+ }+}diff --git a/examples/plugins/jira/icon.svg b/examples/plugins/jira/icon.svgnew file mode 100644index 000000000..7d7b29415--- /dev/null+++ b/examples/plugins/jira/icon.svg@@ -0,0 +1 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><defs><linearGradient id="a" x1="15.5" y1="9.5" x2="10.4" y2="14.7" gradientUnits="userSpaceOnUse"><stop offset=".18" stop-color="#0052cc"/><stop offset="1" stop-color="#2684ff"/></linearGradient><linearGradient id="b" x1="16.6" y1="22.4" x2="21.7" y2="17.3" gradientUnits="userSpaceOnUse"><stop offset=".18" stop-color="#0052cc"/><stop offset="1" stop-color="#2684ff"/></linearGradient></defs><path fill="#2684ff" d="M28.2 15.1 17.3 4.2 16.2 3.2 8 11.4l-3.8 3.7a1 1 0 0 0 0 1.4l7.5 7.5 4.5 4.5 8.2-8.2.1-.1 3.7-3.7a1 1 0 0 0 0-1.4ZM16.2 19.5 12.4 15.8l3.8-3.8 3.7 3.8Z"/><path fill="url(#a)" d="M16.2 12a6.3 6.3 0 0 1 0-8.8L8 11.4l4.4 4.4Z"/><path fill="url(#b)" d="m19.9 15.8-3.7 3.7a6.3 6.3 0 0 1 0 8.9l8.2-8.2Z"/></svg>diff --git a/examples/plugins/jira/jira_test.go b/examples/plugins/jira/jira_test.gonew file mode 100644index 000000000..700c99843--- /dev/null+++ b/examples/plugins/jira/jira_test.go@@ -0,0 +1,504 @@+package main++import (+ "bytes"+ "context"+ "encoding/json"+ "fmt"+ "go/parser"+ "go/token"+ "net/http"+ "net/http/httptest"+ "os"+ "path/filepath"+ "regexp"+ "sort"+ "strconv"+ "strings"+ "sync"+ "testing"+ "time"++ pluginclient "github.com/Tencent/WeKnora/pluginsdk/client"+ "github.com/Tencent/WeKnora/pluginsdk/conformance"+ "github.com/Tencent/WeKnora/pluginsdk/pluginapi"+)++const (+ oauthToken = "access-token-1"+ cloudID = "cloud-1"+ email = "[email protected]"+ apiToken = "api-token"+)++var shanghai, _ = time.LoadLocation("Asia/Shanghai")++// fakeJira is a Jira Cloud site reachable both directly (API token) and+// through the OAuth gateway (/ex/jira/{cloudId}).+type fakeJira struct {+ *httptest.Server+ mu sync.Mutex+ issues map[string]map[string]any // id → issue JSON+ jql []string+}++func newFakeJira(t *testing.T) *fakeJira {+ f := &fakeJira{issues: map[string]map[string]any{}}+ mux := http.NewServeMux()+ mux.HandleFunc("GET /oauth/token/accessible-resources", func(w http.ResponseWriter, r *http.Request) {+ if r.Header.Get("Authorization") != "Bearer "+oauthToken {+ http.Error(w, `{"message":"bad token"}`, http.StatusUnauthorized)+ return+ }+ writeJSON(w, []site{{ID: cloudID, URL: f.URL, Name: "Acme"}})+ })+ api := http.NewServeMux()+ api.HandleFunc("GET /rest/api/3/myself", func(w http.ResponseWriter, _ *http.Request) {+ writeJSON(w, myself{AccountID: "a1", DisplayName: "Me", TimeZone: "Asia/Shanghai"})+ })+ api.HandleFunc("GET /rest/api/3/project/search", func(w http.ResponseWriter, r *http.Request) {+ all := []project{{Key: "ENG", Name: "Engineering"}, {Key: "OPS", Name: "Operations"}}+ start, _ := strconv.Atoi(r.URL.Query().Get("startAt"))+ // One per page, to exercise paging.+ writeJSON(w, map[string]any{"values": all[start : start+1], "isLast": start+1 == len(all)})+ })+ api.HandleFunc("GET /rest/api/3/issuetype", func(w http.ResponseWriter, _ *http.Request) {+ writeJSON(w, []issueType{{Name: "Task"}, {Name: "Bug"}, {Name: "Bug"}, {Name: "Sub-task", Subtask: true}})+ })+ api.HandleFunc("POST /rest/api/3/search/jql", f.search)+ mux.Handle("/ex/jira/"+cloudID+"/", http.StripPrefix("/ex/jira/"+cloudID, bearer(api)))+ mux.Handle("/rest/", basic(api))+ f.Server = httptest.NewServer(mux)+ t.Cleanup(f.Close)+ old := gatewayURL+ gatewayURL = f.URL+ t.Cleanup(func() { gatewayURL = old })+ return f+}++func bearer(h http.Handler) http.Handler {+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if r.Header.Get("Authorization") != "Bearer "+oauthToken {+ http.Error(w, `{"errorMessages":["token"]}`, http.StatusUnauthorized)+ return+ }+ h.ServeHTTP(w, r)+ })+}++func basic(h http.Handler) http.Handler {+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if u, p, ok := r.BasicAuth(); !ok || u != email || p != apiToken {+ http.Error(w, `{"errorMessages":["Client must be authenticated"]}`, http.StatusUnauthorized)+ return+ }+ h.ServeHTTP(w, r)+ })+}++func writeJSON(w http.ResponseWriter, v any) {+ w.Header().Set("Content-Type", "application/json")+ _ = json.NewEncoder(w).Encode(v)+}++var (+ projectClause = regexp.MustCompile(`project = "([A-Z]+)"`)+ updatedClause = regexp.MustCompile(`updated >= "([0-9/: ]+)"`)+)++// search understands the clauses the connector writes and pages two+// issues at a time, oldest update first.+func (f *fakeJira) search(w http.ResponseWriter, r *http.Request) {+ var in struct {+ JQL string `json:"jql"`+ NextPageToken string `json:"nextPageToken"`+ Fields []string `json:"fields"`+ }+ _ = json.NewDecoder(r.Body).Decode(&in)+ if strings.Contains(in.JQL, "BROKEN") {+ http.Error(w, `{"errorMessages":["Error in the JQL Query"]}`, http.StatusBadRequest)+ return+ }+ f.mu.Lock()+ defer f.mu.Unlock()+ f.jql = append(f.jql, in.JQL)+ key := projectClause.FindStringSubmatch(in.JQL)[1]+ var since time.Time+ if m := updatedClause.FindStringSubmatch(in.JQL); m != nil {+ since, _ = time.ParseInLocation("2006/01/02 15:04", m[1], shanghai)+ }+ var list []map[string]any+ for _, is := range f.issues {+ fields := is["fields"].(map[string]any)+ updated, _ := time.Parse("2006-01-02T15:04:05.000-0700", fields["updated"].(string))+ if strings.HasPrefix(is["key"].(string), key+"-") && !updated.Before(since) {+ list = append(list, is)+ }+ }+ sort.Slice(list, func(i, j int) bool {+ updated := func(is map[string]any) string { return is["fields"].(map[string]any)["updated"].(string) }+ return updated(list[i]) < updated(list[j])+ })+ start, _ := strconv.Atoi(in.NextPageToken)+ end := min(start+2, len(list))+ page := map[string]any{"issues": list[start:end], "isLast": end == len(list)}+ if end < len(list) {+ page["nextPageToken"] = strconv.Itoa(end)+ }+ writeJSON(w, page)+}++func (f *fakeJira) put(id, key, summary, updated string) {+ f.mu.Lock()+ defer f.mu.Unlock()+ f.issues[id] = map[string]any{"id": id, "key": key, "fields": map[string]any{+ "summary": summary,+ "updated": updated,+ "created": "2026-09-01T09:00:00.000+0800",+ "status": map[string]any{"name": "In Progress"},+ "description": map[string]any{"type": "doc", "version": 1, "content": []any{+ map[string]any{"type": "paragraph", "content": []any{+ map[string]any{"type": "text", "text": "Steps to "},+ map[string]any{"type": "text", "text": "reproduce", "marks": []any{map[string]any{"type": "strong"}}},+ }},+ }},+ "comment": map[string]any{"total": 3, "comments": []any{map[string]any{+ "author": map[string]any{"displayName": "Ann"},+ "created": "2026-09-02T09:00:00.000+0800",+ "body": map[string]any{+ "type": "doc",+ "content": []any{+ map[string]any{+ "type": "paragraph",+ "content": []any{map[string]any{"type": "text", "text": "Seen on staging"}},+ },+ },+ },+ }}},+ }}+}++func (f *fakeJira) remove(id string) {+ f.mu.Lock()+ defer f.mu.Unlock()+ delete(f.issues, id)+}++func (f *fakeJira) lastJQL() string {+ f.mu.Lock()+ defer f.mu.Unlock()+ return f.jql[len(f.jql)-1]+}++// run is the plugin behind an HTTP server, called like WeKnora calls it.+type run struct {+ t *testing.T+ client *pluginclient.Client+}++func newRun(t *testing.T) *run {+ srv := httptest.NewServer(newPlugin().Handler())+ t.Cleanup(srv.Close)+ return &run{t: t, client: pluginclient.New(srv.URL, nil, nil)}+}++func tokenInstance(f *fakeJira, settings map[string]any) map[string]any {+ return map[string]any{+ "credentials": map[string]any{"auth": "token", "base_url": f.URL + "/", "email": email, "api_token": apiToken},+ "settings": settings,+ }+}++func oauthInstance(site string) map[string]any {+ // WeKnora has already swapped the "oauth:<id>" reference for a token.+ return map[string]any{+ "credentials": map[string]any{"auth": "oauth", "account": oauthToken, "site": site},+ "settings": map[string]any{},+ }+}++type fetched struct {+ items []pluginapi.FetchedItem+ checkpoints int+ cursor *pluginapi.Cursor+}++func (r *run) fetch(instance map[string]any, mode string, cursor *pluginapi.Cursor, projects ...string) fetched {+ r.t.Helper()+ var out fetched+ end, err := r.client.Stream(context.Background(), pluginapi.ConnectorFetchPath("jira"),+ pluginapi.Envelope{Config: pluginapi.Config{Instance: instance}},+ pluginapi.FetchInput{Mode: mode, Cursor: cursor, ResourceIDs: projects},+ func(ev pluginapi.Event) error {+ switch ev.Type {+ case pluginapi.EventItem:+ var it pluginapi.FetchedItem+ if err := json.Unmarshal(ev.Data, &it); err != nil {+ return err+ }+ out.items = append(out.items, it)+ case pluginapi.EventCheckpoint:+ out.checkpoints+++ }+ return nil+ })+ if err != nil {+ r.t.Fatalf("fetch: %v", err)+ }+ out.cursor = &pluginapi.Cursor{}+ if err := json.Unmarshal(end, out.cursor); err != nil {+ r.t.Fatal(err)+ }+ return out+}++func (r *run) call(path string, instance map[string]any, input, out any) error {+ return r.client.Call(context.Background(), path,+ pluginapi.Envelope{Config: pluginapi.Config{Instance: instance}}, input, out)+}++func summary(items []pluginapi.FetchedItem) []string {+ var out []string+ for _, it := range items {+ if it.IsDeleted {+ out = append(out, "-"+it.ExternalID)+ } else {+ out = append(out, it.ExternalID+" "+it.Title)+ }+ }+ return out+}++func TestSyncIsIncrementalAndReportsDeletions(t *testing.T) {+ f := newFakeJira(t)+ f.put("101", "ENG-1", "Login fails", "2026-09-20T10:00:00.000+0800")+ f.put("102", "ENG-2", "Slow search", "2026-09-21T10:00:30.000+0800")+ f.put("103", "ENG-3", "Crash on save", "2026-09-22T10:00:00.000+0800")+ f.put("201", "OPS-1", "Not selected", "2026-09-22T10:00:00.000+0800")+ r := newRun(t)+ inst := tokenInstance(f, map[string]any{"issue_types": []string{"Bug", `Odd "type"`}, "jql": "labels = x"})++ full := r.fetch(inst, pluginapi.FetchFull, nil, "ENG")+ if got := summary(full.items); strings.Join(+ got,+ "|",+ ) != "101 ENG-1 Login fails|102 ENG-2 Slow search|103 ENG-3 Crash on save" {+ t.Fatalf("full sync = %v", got)+ }+ if full.checkpoints != 2 {+ t.Fatalf("a checkpoint per page, got %d", full.checkpoints)+ }+ wantJQL := `project = "ENG" AND issuetype in ("Bug", "Odd \"type\"") AND (labels = x) ORDER BY updated ASC`+ if jql := f.lastJQL(); jql != wantJQL {+ t.Fatalf("jql = %s", jql)+ }+ doc := string(full.items[0].Content)+ for _, want := range []string{+ "# ENG-1: Login fails", "- **Status:** In Progress", "- **Link:** " + f.URL + "/browse/ENG-1",+ "## Description\n\nSteps to **reproduce**", "### Ann · 2026-09-02 09:00 +0800\n\nSeen on staging",+ "_2 more comments are not included._",+ } {+ if !strings.Contains(doc, want) {+ t.Errorf("document lacks %q:\n%s", want, doc)+ }+ }+ if it := full.items[0]; it.SourceResourceID != "ENG" || it.Metadata["jira_key"] != "ENG-1" ||+ it.FileName != "ENG-1 Login fails.md" || it.UpdatedAt == nil {+ t.Fatalf("item = %+v", it)+ }++ // Incremental: from the newest update seen, in the user's time zone.+ f.put("102", "ENG-2", "Slow search (again)", "2026-09-25T08:00:00.000+0800")+ inc := r.fetch(inst, pluginapi.FetchIncremental, full.cursor, "ENG")+ if !strings.Contains(f.lastJQL(), `updated >= "2026/09/22 10:00"`) {+ t.Fatalf("incremental jql = %s", f.lastJQL())+ }+ if got := summary(inc.items); strings.Join(got, "|") != "103 ENG-3 Crash on save|102 ENG-2 Slow search (again)" {+ t.Fatalf("incremental = %v", got)+ }++ // A full sync reports what disappeared, once.+ f.remove("101")+ again := r.fetch(inst, pluginapi.FetchFull, inc.cursor, "ENG")+ if got := summary(again.items); got[len(got)-1] != "-101" || len(got) != 3 {+ t.Fatalf("full sync after a deletion = %v", got)+ }+ once := r.fetch(inst, pluginapi.FetchFull, again.cursor, "ENG")+ for _, it := range once.items {+ if it.IsDeleted {+ t.Fatalf("deletion reported twice: %v", summary(once.items))+ }+ }+}++func TestOAuthAccountsReachTheirSites(t *testing.T) {+ f := newFakeJira(t)+ f.put("101", "ENG-1", "Login fails", "2026-09-20T10:00:00.000+0800")+ r := newRun(t)++ var sites pluginapi.OptionsOutput+ err := r.call(pluginapi.OptionsPath("sites"), oauthInstance(""), pluginapi.OptionsInput{Field: "site"}, &sites)+ if err != nil {+ t.Fatal(err)+ }+ if len(sites.Options) != 1 || sites.Options[0].Value != cloudID || sites.Options[0].Label != "Acme" {+ t.Fatalf("sites = %+v", sites)+ }+ var types pluginapi.OptionsOutput+ err = r.call(pluginapi.OptionsPath("issue_types"), oauthInstance(cloudID), pluginapi.OptionsInput{}, &types)+ if err != nil {+ t.Fatal(err)+ }+ if fmt.Sprint(types.Options) != "[{Bug } {Sub-task } {Task }]" {+ t.Fatalf("issue types = %v", types.Options)+ }+ var res pluginapi.ListResourcesOutput+ listPath := pluginapi.ConnectorListResourcesPath("jira")+ err = r.call(listPath, oauthInstance(cloudID), pluginapi.ListResourcesInput{}, &res)+ if err != nil {+ t.Fatal(err)+ }+ if len(res.Resources) != 2 || res.Resources[1].ExternalID != "OPS" || res.Resources[0].URL != f.URL+"/browse/ENG" {+ t.Fatalf("projects = %+v", res.Resources)+ }+ got := r.fetch(oauthInstance(cloudID), pluginapi.FetchFull, nil, "ENG")+ if len(got.items) != 1 || got.items[0].URL != f.URL+"/browse/ENG-1" {+ t.Fatalf("oauth sync = %v", summary(got.items))+ }+}++func TestProblemsReachTheForm(t *testing.T) {+ f := newFakeJira(t)+ r := newRun(t)+ cases := []struct {+ name string+ instance map[string]any+ code pluginapi.ErrorCode+ }{+ {"no account", map[string]any{"credentials": map[string]any{"auth": "oauth"}}, pluginapi.CodeInvalidConfig},+ {"site not granted", oauthInstance("cloud-2"), pluginapi.CodeInvalidConfig},+ {+ "expired token",+ map[string]any{"credentials": map[string]any{"auth": "oauth", "account": "old", "site": cloudID}},+ pluginapi.CodeUnauthorized,+ },+ {+ "missing token fields",+ map[string]any{"credentials": map[string]any{"auth": "token"}},+ pluginapi.CodeInvalidConfig,+ },+ {"wrong api token", map[string]any{"credentials": map[string]any{+ "auth": "token", "base_url": f.URL, "email": email, "api_token": "nope",+ }}, pluginapi.CodeUnauthorized},+ }+ for _, tc := range cases {+ err := r.call(pluginapi.ConnectorValidatePath("jira"), tc.instance, struct{}{}, nil)+ if pe, ok := pluginapi.AsError(err); !ok || pe.Code != tc.code {+ t.Errorf("%s: %v", tc.name, err)+ }+ }+ // Messages about the form speak the user's language.+ err := r.client.Call(context.Background(), pluginapi.OptionsPath("sites"), pluginapi.Envelope{+ Context: pluginapi.Context{Locale: "zh-CN"},+ Config: pluginapi.Config{Instance: map[string]any{"credentials": map[string]any{"auth": "oauth"}}},+ }, pluginapi.OptionsInput{}, nil)+ if pe, ok := pluginapi.AsError(err); !ok || pe.Message != msgConnectAccount.zh {+ t.Fatalf("zh-CN hint = %v", err)+ }+ if err := r.call(pluginapi.ConnectorValidatePath("jira"), tokenInstance(f, nil), struct{}{}, nil); err != nil {+ t.Fatalf("valid token: %v", err)+ }+ _, err = r.client.Stream(+ context.Background(),+ pluginapi.ConnectorFetchPath("jira"),+ pluginapi.Envelope{Config: pluginapi.Config{Instance: tokenInstance(f, map[string]any{"jql": "BROKEN"})}},+ pluginapi.FetchInput{+ Mode: pluginapi.FetchFull,+ ResourceIDs: []string{"ENG"},+ },+ func(pluginapi.Event) error { return nil },+ )+ if pe, ok := pluginapi.AsError(err); !ok || pe.Code != pluginapi.CodeInvalidConfig ||+ !strings.Contains(pe.Message, "JQL") {+ t.Fatalf("bad jql = %v", err)+ }+}++func TestRateLimitsAreRetryable(t *testing.T) {+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {+ w.Header().Set("Retry-After", "7")+ w.WriteHeader(http.StatusTooManyRequests)+ }))+ defer srv.Close()+ c := &client{api: srv.URL}+ _, err := c.myself(context.Background())+ pe, ok := pluginapi.AsError(err)+ if !ok || pe.Code != pluginapi.CodeRateLimited || !pe.Retryable || pe.Details.RetryAfter != 7 {+ t.Fatalf("429 = %v", err)+ }+}++func TestADFToMarkdown(t *testing.T) {+ doc, err := os.ReadFile("testdata/adf.json")+ if err != nil {+ t.Fatal(err)+ }+ want := "## Plan\n\n- one\n 1. nested\n- [docs](https://example.com) by @Ann\n\n```go\nx := 1\n```\n\n" ++ "| a\\|b |\n| --- |\n| 1 |\n\n[attachment]\n\nkept"+ if got := adfToMarkdown(doc); got != want {+ t.Fatalf("got:\n%s\nwant:\n%s", got, want)+ }+ if adfToMarkdown(json.RawMessage(`"plain"`)) != "plain" || adfToMarkdown(nil) != "" {+ t.Fatal("plain strings pass through")+ }+}++func TestJQLDatesUseTheUsersZone(t *testing.T) {+ since := time.Date(2026, 9, 22, 2, 0, 59, 0, time.UTC)+ got := buildJQL("ENG", settings{}, since, shanghai)+ if got != `project = "ENG" AND updated >= "2026/09/22 10:00" ORDER BY updated ASC` {+ t.Fatal(got)+ }+}++// The example must stay an external plugin: the SDK and ordinary libraries,+// nothing from WeKnora's internals.+func TestPluginImportsNoInternals(t *testing.T) {+ files, _ := filepath.Glob("*.go")+ fset := token.NewFileSet()+ for _, f := range files {+ if strings.HasSuffix(f, "_test.go") {+ continue+ }+ src, err := os.ReadFile(f)+ if err != nil {+ t.Fatal(err)+ }+ parsed, err := parser.ParseFile(fset, f, src, parser.ImportsOnly)+ if err != nil {+ t.Fatal(err)+ }+ for _, imp := range parsed.Imports {+ if strings.Contains(imp.Path.Value, "github.com/Tencent/WeKnora/internal") {+ t.Errorf("%s imports %s", f, imp.Path.Value)+ }+ }+ }+}++func TestPluginPassesConformance(t *testing.T) {+ srv := httptest.NewServer(newPlugin().Handler())+ defer srv.Close()+ rep := conformance.Run(context.Background(), conformance.Target{+ Client: pluginclient.New(srv.URL, nil, nil),+ Raw: func(ctx context.Context, path string, body []byte) (*http.Response, error) {+ req, _ := http.NewRequestWithContext(ctx, http.MethodPost, srv.URL+path, bytes.NewReader(body))+ return http.DefaultClient.Do(req)+ },+ })+ for _, r := range rep.Results {+ if !r.Passed {+ t.Errorf("%s: %s", r.Name, r.Detail)+ }+ }+}diff --git a/examples/plugins/jira/main.go b/examples/plugins/jira/main.gonew file mode 100644index 000000000..7ab396a67--- /dev/null+++ b/examples/plugins/jira/main.go@@ -0,0 +1,451 @@+// Command jira syncs Jira Cloud issues into WeKnora knowledge bases. It is the+// fullest example plugin:+//+// - a data source connector with incremental sync, checkpoints and+// deletions;+// - an OAuth field (x-oauth): WeKnora runs Atlassian's consent flow with+// the platform's OAuth app and hands the plugin a fresh access token;+// - dynamic choices (x-options): the sites an account can reach and the+// site's issue types;+// - a skill shipped in the package.+//+// Build a package with ./package.sh; install it under System administration+// → Plugin management.+package main++import (+ "context"+ "encoding/json"+ "fmt"+ "log"+ "slices"+ "sort"+ "strings"+ "time"+ "unicode/utf8"++ "github.com/Tencent/WeKnora/pluginsdk"+ "github.com/Tencent/WeKnora/pluginsdk/pluginapi"+)++// Version must match plugin.yaml.+const Version = "1.0.0"++func main() {+ if err := newPlugin().Serve(); err != nil {+ log.Fatal(err)+ }+}++func newPlugin() *pluginsdk.Plugin {+ p := pluginsdk.New(pluginsdk.Info{ID: "weknora-examples.jira", Version: Version})+ p.Connector("jira", connector{})+ p.Options("sites", siteOptions)+ p.Options("issue_types", issueTypeOptions)+ return p+}++// settings are the connector's x-group: settings fields.+type settings struct {+ IssueTypes []string `json:"issue_types"`+ JQL string `json:"jql"`+ IncludeComments *bool `json:"include_comments"`+}++func (s settings) comments() bool { return s.IncludeComments == nil || *s.IncludeComments }++func decode(cfg pluginsdk.ConnectorConfig) (credentials, settings, error) {+ var cr credentials+ var st settings+ if err := remarshal(cfg.Credentials, &cr); err != nil {+ return cr, st, pluginapi.InvalidConfig("credentials: "+err.Error(), nil)+ }+ if err := remarshal(cfg.Settings, &st); err != nil {+ return cr, st, pluginapi.InvalidConfig("settings: "+err.Error(), nil)+ }+ return cr, st, nil+}++func remarshal(in, out any) error {+ b, err := json.Marshal(in)+ if err != nil {+ return err+ }+ return json.Unmarshal(b, out)+}++type connector struct{}++// Validate signs in to the site.+func (connector) Validate(ctx context.Context, call *pluginsdk.Call, cfg pluginsdk.ConnectorConfig) error {+ cr, _, err := decode(cfg)+ if err != nil {+ return err+ }+ c, err := newClient(ctx, cr, call.Locale)+ if err != nil {+ return err+ }+ _, err = c.myself(ctx)+ return err+}++// ListResources offers the projects the user can browse.+func (connector) ListResources(+ ctx context.Context, call *pluginsdk.Call, cfg pluginsdk.ConnectorConfig, parentID string,+) ([]pluginapi.Resource, error) {+ if parentID != "" {+ return nil, nil+ }+ cr, _, err := decode(cfg)+ if err != nil {+ return nil, err+ }+ c, err := newClient(ctx, cr, call.Locale)+ if err != nil {+ return nil, err+ }+ projects, err := c.projects(ctx)+ if err != nil {+ return nil, err+ }+ out := make([]pluginapi.Resource, 0, len(projects))+ for _, p := range projects {+ out = append(out, pluginapi.Resource{+ ExternalID: p.Key, Name: p.Name, Type: "project", Description: p.Key,+ URL: c.siteURL + "/browse/" + p.Key,+ })+ }+ return out, nil+}++// syncState is the cursor: per project, the newest update seen (where the+// next incremental sync starts) and the issues it holds (so a full sync can+// tell which were deleted).+type syncState struct {+ Projects map[string]*projectState `json:"projects"`+}++type projectState struct {+ Since time.Time `json:"since"`+ IDs []string `json:"ids"`+}++func stateFrom(c *pluginapi.Cursor) syncState {+ st := syncState{Projects: map[string]*projectState{}}+ if c != nil {+ _ = remarshal(c.State, &st)+ if st.Projects == nil {+ st.Projects = map[string]*projectState{}+ }+ }+ return st+}++func (s syncState) cursor(now time.Time) pluginapi.Cursor {+ var state map[string]any+ _ = remarshal(s, &state)+ return pluginapi.Cursor{LastSyncTime: &now, State: state}+}++// Fetch syncs the selected projects. Issues come oldest update first, so the+// cursor can advance with every page; a full sync also reports the issues+// that disappeared (deleted, moved out, or no longer matching the filter).+func (connector) Fetch(+ ctx context.Context, call *pluginsdk.Call, cfg pluginsdk.ConnectorConfig, in pluginapi.FetchInput,+ s *pluginsdk.Stream,+) (*pluginapi.Cursor, error) {+ cr, st, err := decode(cfg)+ if err != nil {+ return nil, err+ }+ keys := in.ResourceIDs+ if len(keys) == 0 {+ keys = cfg.ResourceIDs+ }+ if len(keys) == 0 {+ return nil, pluginapi.InvalidConfig(say(call.Locale, msgNoProjects), nil)+ }+ c, err := newClient(ctx, cr, call.Locale)+ if err != nil {+ return nil, err+ }+ me, err := c.myself(ctx)+ if err != nil {+ return nil, err+ }+ // JQL reads dates in the user's time zone.+ loc, err := time.LoadLocation(me.TimeZone)+ if err != nil || me.TimeZone == "" {+ loc = time.UTC+ }++ prev := stateFrom(in.Cursor)+ incremental := in.Mode == pluginapi.FetchIncremental && in.Cursor != nil+ // Checkpoints are complete snapshots: projects not reached yet keep+ // their previous state.+ next := syncState{Projects: map[string]*projectState{}}+ for _, key := range keys {+ if p := prev.Projects[key]; p != nil {+ cp := *p+ next.Projects[key] = &cp+ } else {+ next.Projects[key] = &projectState{}+ }+ }+ seen := map[string]bool{}+ now := time.Now().UTC()++ for _, key := range keys {+ ps := next.Projects[key]+ var since time.Time+ if incremental {+ since = ps.Since+ }+ known := map[string]bool{}+ for _, id := range ps.IDs {+ known[id] = true+ }+ _ = s.Progress("syncing " + key)+ err := c.search(ctx, buildJQL(key, st, since, loc), st.comments(), func(page []issue) error {+ for i := range page {+ is := &page[i]+ if err := s.Item(c.item(is, key)); err != nil {+ return err+ }+ seen[is.ID], known[is.ID] = true, true+ if is.Fields.Updated.After(ps.Since) {+ ps.Since = is.Fields.Updated.Time+ }+ }+ ps.IDs = sortedKeys(known)+ return s.Checkpoint(next.cursor(now))+ })+ if err != nil {+ return nil, err+ }+ }++ if !incremental {+ // Everything was listed: what the last sync had and this one did+ // not see is gone.+ for _, key := range keys {+ var kept []string+ if p := prev.Projects[key]; p != nil {+ for _, id := range p.IDs {+ if seen[id] {+ continue+ }+ gone := pluginapi.FetchedItem{ExternalID: id, IsDeleted: true, SourceResourceID: key}+ if err := s.Item(gone); err != nil {+ return nil, err+ }+ }+ }+ for _, id := range next.Projects[key].IDs {+ if seen[id] {+ kept = append(kept, id)+ }+ }+ next.Projects[key].IDs = kept+ }+ }+ cur := next.cursor(now)+ return &cur, nil+}++func sortedKeys(m map[string]bool) []string {+ out := make([]string, 0, len(m))+ for k := range m {+ out = append(out, k)+ }+ sort.Strings(out)+ return out+}++// buildJQL is one project's query: the settings' filters, the issues updated+// since the last sync (to the minute, JQL's precision), oldest first.+func buildJQL(key string, st settings, since time.Time, loc *time.Location) string {+ parts := []string{"project = " + quote(key)}+ if len(st.IssueTypes) > 0 {+ types := make([]string, len(st.IssueTypes))+ for i, t := range st.IssueTypes {+ types[i] = quote(t)+ }+ parts = append(parts, "issuetype in ("+strings.Join(types, ", ")+")")+ }+ if extra := strings.TrimSpace(st.JQL); extra != "" {+ parts = append(parts, "("+extra+")")+ }+ if !since.IsZero() {+ parts = append(parts, "updated >= "+quote(since.In(loc).Format("2006/01/02 15:04")))+ }+ return strings.Join(parts, " AND ") + " ORDER BY updated ASC"+}++func quote(s string) string {+ return `"` + strings.NewReplacer(`\`, `\\`, `"`, `\"`).Replace(s) + `"`+}++// item turns an issue into a Markdown document.+func (c *client) item(is *issue, projectKey string) pluginapi.FetchedItem {+ f := &is.Fields+ var b strings.Builder+ fmt.Fprintf(&b, "# %s: %s\n\n", is.Key, f.Summary)+ facts := [][2]string{+ {"Type", nameOf(f.IssueType)},+ {"Status", nameOf(f.Status)},+ {"Priority", nameOf(f.Priority)},+ {"Resolution", nameOf(f.Resolution)},+ {"Assignee", userOf(f.Assignee)},+ {"Reporter", userOf(f.Reporter)},+ {"Labels", strings.Join(f.Labels, ", ")},+ {"Created", stamp(f.Created)},+ {"Updated", stamp(f.Updated)},+ }+ if f.Parent != nil {+ facts = append(facts, [2]string{"Parent", f.Parent.Key})+ }+ for _, kv := range facts {+ if kv[1] != "" {+ fmt.Fprintf(&b, "- **%s:** %s\n", kv[0], kv[1])+ }+ }+ url := c.siteURL + "/browse/" + is.Key+ fmt.Fprintf(&b, "- **Link:** %s\n", url)+ if desc := adfToMarkdown(f.Description); desc != "" {+ b.WriteString("\n## Description\n\n" + desc + "\n")+ }+ if f.Comment != nil && len(f.Comment.Comments) > 0 {+ b.WriteString("\n## Comments\n")+ for _, cm := range f.Comment.Comments {+ fmt.Fprintf(&b, "\n### %s · %s\n\n%s\n", userOf(cm.Author), stamp(cm.Created), adfToMarkdown(cm.Body))+ }+ if more := f.Comment.Total - len(f.Comment.Comments); more > 0 {+ fmt.Fprintf(&b, "\n_%d more comments are not included._\n", more)+ }+ }+ created, updated := f.Created.Time, f.Updated.Time+ return pluginapi.FetchedItem{+ ExternalID: is.ID,+ Title: is.Key + " " + f.Summary,+ Content: []byte(b.String()),+ ContentType: "text/markdown",+ FileName: fileName(is.Key + " " + f.Summary),+ URL: url,+ CreatedAt: nonZero(created),+ UpdatedAt: nonZero(updated),+ SourceResourceID: projectKey,+ Metadata: map[string]string{+ "channel": "jira", "jira_key": is.Key, "project": projectKey, "status": nameOf(f.Status),+ "issue_type": nameOf(f.IssueType), "assignee": userOf(f.Assignee), "priority": nameOf(f.Priority),+ "labels": strings.Join(f.Labels, ","),+ },+ }+}++func nameOf(n *named) string {+ if n == nil {+ return ""+ }+ return n.Name+}++func userOf(u *user) string {+ if u == nil {+ return ""+ }+ return u.DisplayName+}++func stamp(t jiraTime) string {+ if t.IsZero() {+ return ""+ }+ return t.Format("2006-01-02 15:04 -0700")+}++func nonZero(t time.Time) *time.Time {+ if t.IsZero() {+ return nil+ }+ return &t+}++const maxFileNameBytes = 200++var fileNameReplacer = strings.NewReplacer(+ "/", "_", "\\", "_", ":", "_", "*", "_", "?", "_", "\"", "_", "<", "_", ">", "_", "|", "_",+ "\n", " ", "\r", " ", "\t", " ",+)++// fileName makes a title safe as a file name: hostile punctuation replaced,+// at most 200 bytes without splitting a rune.+func fileName(title string) string {+ name := strings.TrimSpace(fileNameReplacer.Replace(title))+ if name == "" {+ return "issue.md"+ }+ for len(name) > maxFileNameBytes {+ _, size := utf8.DecodeLastRuneInString(name)+ name = name[:len(name)-size]+ }+ return name + ".md"+}++// siteOptions lists the Jira sites the connected account granted.+func siteOptions(ctx context.Context, call *pluginsdk.Call, _ pluginapi.OptionsInput) ([]pluginapi.Option, error) {+ var cfg pluginsdk.ConnectorConfig+ if err := call.DecodeInstance(&cfg); err != nil {+ return nil, err+ }+ cr, _, err := decode(cfg)+ if err != nil {+ return nil, err+ }+ if cr.Account == "" {+ return nil, pluginapi.InvalidConfig(say(call.Locale, msgConnectAccount),+ map[string]string{"credentials.account": "required"})+ }+ sites, err := accessibleSites(ctx, cr.Account)+ if err != nil {+ return nil, err+ }+ out := make([]pluginapi.Option, 0, len(sites))+ for _, s := range sites {+ out = append(out, pluginapi.Option{Value: s.ID, Label: s.Name, Description: s.URL})+ }+ return out, nil+}++// issueTypeOptions lists the site's issue types by name (JQL matches names).+func issueTypeOptions(ctx context.Context, call *pluginsdk.Call, _ pluginapi.OptionsInput) ([]pluginapi.Option, error) {+ var cfg pluginsdk.ConnectorConfig+ if err := call.DecodeInstance(&cfg); err != nil {+ return nil, err+ }+ cr, _, err := decode(cfg)+ if err != nil {+ return nil, err+ }+ c, err := newClient(ctx, cr, call.Locale)+ if err != nil {+ return nil, err+ }+ types, err := c.issueTypes(ctx)+ if err != nil {+ return nil, err+ }+ var names []string+ for _, t := range types {+ if !slices.Contains(names, t.Name) {+ names = append(names, t.Name)+ }+ }+ sort.Strings(names)+ out := make([]pluginapi.Option, len(names))+ for i, n := range names {+ out[i] = pluginapi.Option{Value: n}+ }+ return out, nil+}diff --git a/examples/plugins/jira/messages.go b/examples/plugins/jira/messages.gonew file mode 100644index 000000000..9bc631346--- /dev/null+++ b/examples/plugins/jira/messages.go@@ -0,0 +1,23 @@+package main++import "strings"++// Messages the form shows, in the user's language (call.Locale). Errors+// that quote Jira stay in Jira's words.+type message struct{ en, zh string }++var (+ msgConnectAccount = message{"Connect an Atlassian account first.", "请先连接 Atlassian 账号。"}+ msgChooseSite = message{"Choose a site.", "请选择站点。"}+ msgSiteGone = message{"The account cannot reach this site any more.", "该账号已无法访问此站点。"}+ msgTokenFields = message{"Enter the site URL, email and API token first.", "请先填写站点地址、邮箱和 API 令牌。"}+ msgUnknownAuth = message{"Unknown sign-in method.", "未知的登录方式。"}+ msgNoProjects = message{"Select at least one project to sync.", "请至少选择一个要同步的项目。"}+)++func say(locale string, m message) string {+ if strings.HasPrefix(strings.ToLower(locale), "zh") {+ return m.zh+ }+ return m.en+}diff --git a/examples/plugins/jira/package.sh b/examples/plugins/jira/package.shnew file mode 100755index 000000000..f9219fe29--- /dev/null+++ b/examples/plugins/jira/package.sh@@ -0,0 +1,21 @@+#!/usr/bin/env bash+# Builds the Jira example plugin for the platforms WeKnora runs on and zips it+# into a .wkp package: plugin.yaml, schemas, the skill, icon and bin/<os>-<arch>/jira.+set -euo pipefail+cd "$(dirname "$0")"+version=$(sed -n 's/^version: //p' plugin.yaml)+out=${1:-"weknora-examples-jira-${version}.wkp"}+stage=$(mktemp -d)+trap 'rm -rf "$stage"' EXIT+cp plugin.yaml icon.svg "$stage"/+cp -r schemas skills "$stage"/+for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64; do+ os=${target%/*}+ arch=${target#*/}+ bin="$stage/bin/${os}-${arch}/jira"+ [ "$os" = windows ] && bin="$bin.exe"+ CGO_ENABLED=0 GOOS=$os GOARCH=$arch go build -trimpath -ldflags="-s -w" -o "$bin" .+done+rm -f "$out"+(cd "$stage" && zip -qr - .) > "$out"+echo "wrote $out"diff --git a/examples/plugins/jira/plugin.yaml b/examples/plugins/jira/plugin.yamlnew file mode 100644index 000000000..8f08ce448--- /dev/null+++ b/examples/plugins/jira/plugin.yaml@@ -0,0 +1,42 @@+schemaVersion: 1+id: weknora-examples.jira+version: 1.0.0+apiVersion: weknora.plugin/v1+name: { en-US: Jira, zh-CN: Jira }+description:+ en-US: Sync Jira Cloud issues, with their comments, into a knowledge base, and a skill for triaging them. Connects with Atlassian OAuth or an API token; shows dynamic form options and OAuth fields.+ zh-CN: 把 Jira Cloud 的问题(含评论)同步到知识库,并提供问题分诊技能。支持 Atlassian OAuth 授权或 API 令牌;演示表单动态选项与 OAuth 字段。+publisher: { id: weknora-examples, name: WeKnora examples }+homepage: https://github.com/Tencent/WeKnora/tree/main/examples/plugins/jira+license: MIT+icon: icon.svg+runtime:+ type: host+ kind: binary+ entry: "bin/{os}-{arch}/jira"+ resources: { cpu: 500m, memory: 256Mi }+permissions:+ # The OAuth API gateway and the sites themselves. WeKnora, not the plugin,+ # talks to auth.atlassian.com.+ egress: [api.atlassian.com, "*.atlassian.net"]+config:+ # The platform's Atlassian OAuth 2.0 (3LO) app. Without it, workspaces can+ # still connect with an API token.+ system: schemas/system.yaml+contributes:+ connectors:+ - id: jira+ name: { en-US: Jira, zh-CN: Jira }+ description:+ en-US: Issues of the selected Jira Cloud projects, with comments+ zh-CN: 同步所选 Jira Cloud 项目的问题及评论+ icon: icon.svg+ capabilities: [incremental, streaming]+ instanceSchema: schemas/connector.yaml+ skills:+ - id: jira-triage+ name: { en-US: Jira triage, zh-CN: Jira 问题分诊 }+ description:+ en-US: Find duplicates, related work and owners of a Jira issue in the synced issues+ zh-CN: 在已同步的问题中查找重复、相关工作和负责人+ path: skills/jira-triagediff --git a/examples/plugins/jira/schemas/connector.yaml b/examples/plugins/jira/schemas/connector.yamlnew file mode 100644index 000000000..f45fec6d0--- /dev/null+++ b/examples/plugins/jira/schemas/connector.yaml@@ -0,0 +1,99 @@+type: object+# Fields hidden by x-visible-if are not required.+required: [auth, account, site, base_url, email, api_token]+properties:+ auth:+ type: string+ title: Sign in with+ default: oauth+ x-order: 1+ oneOf:+ - const: oauth+ title: Atlassian account (OAuth)+ x-i18n: { title: { zh-CN: Atlassian 账号(OAuth) } }+ - const: token+ title: API token+ x-i18n: { title: { zh-CN: API 令牌 } }+ x-i18n:+ title: { zh-CN: 登录方式 }+ account:+ type: string+ title: Atlassian account+ description: Needs the platform's OAuth app (plugin management → Jira)+ x-order: 2+ x-visible-if: { auth: oauth }+ x-oauth:+ authorizeUrl: https://auth.atlassian.com/authorize+ tokenUrl: https://auth.atlassian.com/oauth/token+ scopes: [read:jira-work, read:jira-user, offline_access]+ clientId: ${system.client_id}+ clientSecret: ${system.client_secret}+ params: { audience: api.atlassian.com, prompt: consent }+ x-i18n:+ title: { zh-CN: Atlassian 账号 }+ description: { zh-CN: 需要平台先配置 OAuth 应用(插件管理 → Jira) }+ site:+ type: string+ title: Site+ description: The Jira site the account can reach+ x-order: 3+ x-visible-if: { auth: oauth }+ x-options: { name: sites, dependsOn: [account] }+ x-i18n:+ title: { zh-CN: 站点 }+ description: { zh-CN: 该账号可访问的 Jira 站点 }+ base_url:+ type: string+ title: Site URL+ x-order: 4+ x-visible-if: { auth: token }+ x-placeholder: https://your-team.atlassian.net+ pattern: "^https://[A-Za-z0-9-]+\\.atlassian\\.net/?$"+ x-i18n:+ title: { zh-CN: 站点地址 }+ email:+ type: string+ title: Email+ x-order: 5+ x-visible-if: { auth: token }+ format: email+ x-i18n:+ title: { zh-CN: 邮箱 }+ api_token:+ type: string+ title: API token+ description: Create one at id.atlassian.com → Security → API tokens+ x-order: 6+ x-secret: true+ x-visible-if: { auth: token }+ x-i18n:+ title: { zh-CN: API 令牌 }+ description: { zh-CN: 在 id.atlassian.com → 安全 → API 令牌 中创建 }+ issue_types:+ type: array+ items: { type: string }+ title: Issue types+ description: Only these types; leave empty for all+ x-order: 10+ x-group: settings+ x-options: { name: issue_types, dependsOn: [auth, site, base_url, email] }+ x-i18n:+ title: { zh-CN: 问题类型 }+ description: { zh-CN: 只同步这些类型,留空表示全部 }+ jql:+ type: string+ title: Extra JQL filter+ description: "Added to each project's query, e.g. statusCategory != Done"+ x-order: 11+ x-group: settings+ x-i18n:+ title: { zh-CN: 附加 JQL 条件 }+ description: { zh-CN: "追加到每个项目的查询,例如 statusCategory != Done" }+ include_comments:+ type: boolean+ title: Include comments+ default: true+ x-order: 12+ x-group: settings+ x-i18n:+ title: { zh-CN: 包含评论 }diff --git a/examples/plugins/jira/schemas/system.yaml b/examples/plugins/jira/schemas/system.yamlnew file mode 100644index 000000000..eeef01988--- /dev/null+++ b/examples/plugins/jira/schemas/system.yaml@@ -0,0 +1,17 @@+type: object+properties:+ client_id:+ type: string+ title: OAuth client ID+ description: "Client ID of an OAuth 2.0 (3LO) app in the Atlassian developer console, with the Jira API scopes read:jira-work and read:jira-user and the callback URL <WeKnora address>/api/v1/plugin-oauth/callback"+ x-order: 1+ x-i18n:+ title: { zh-CN: OAuth 客户端 ID }+ description: { zh-CN: "在 Atlassian 开发者控制台创建的 OAuth 2.0 (3LO) 应用的 Client ID。应用需开通 Jira API 的 read:jira-work 与 read:jira-user 权限,回调地址填 <WeKnora 地址>/api/v1/plugin-oauth/callback" }+ client_secret:+ type: string+ title: OAuth client secret+ x-secret: true+ x-order: 2+ x-i18n:+ title: { zh-CN: OAuth 客户端密钥 }diff --git a/examples/plugins/jira/skills/jira-triage/SKILL.md b/examples/plugins/jira/skills/jira-triage/SKILL.mdnew file mode 100644index 000000000..27b5a927e--- /dev/null+++ b/examples/plugins/jira/skills/jira-triage/SKILL.md@@ -0,0 +1,40 @@+---+name: jira-triage+description: Triage a Jira issue against the issues synced into the knowledge base - find duplicates, related work, likely owners and a suggested priority. Use when the user pastes a Jira key or a bug report and asks whether it is known, who should take it, or how urgent it is.+---+# Jira triage++The Jira data source stores each issue as one Markdown document titled+`<KEY> <summary>`. It starts with a fact list (Type, Status, Priority,+Resolution, Assignee, Reporter, Labels, Created, Updated, Parent, Link), then+`## Description` and `## Comments`.++## Steps++1. **Understand the report.** If the user gave a key (`ENG-123`), find that+ issue first with `search_knowledge` on the key and read it with+ `read_document`. Otherwise work from the text they pasted. Note the+ component, the symptom, error messages and the version or environment.+2. **Look for duplicates.** Search with the symptom in a few phrasings and+ with any exact error message. Read the closest matches. Treat as a+ duplicate only when the symptom and the conditions both match, not only+ the area.+3. **Find related work.** Look for open issues in the same area, recent+ fixes (Resolution set, Updated recently) and parent epics.+4. **Suggest an owner.** Prefer the assignee of the duplicates or of recent+ fixes in the same area. Say how many issues support the suggestion.+5. **Suggest a priority.** Compare with the priorities of similar issues and+ weigh impact (data loss, security, many users) over annoyance.++## Answer++Reply in the user's language with:++- **Verdict:** duplicate of `<KEY>`, related to `<KEYS>`, or new.+- **Evidence:** one line per issue: key, summary, status, and why it+ matches. Link each with the Link from its document.+- **Owner** and **priority** suggestions, with the reason.+- **Missing information** the reporter should add, if any.++Only cite issues you read. The knowledge base may lag Jira by one sync; say so+when the newest issue you found is older than a day.diff --git a/examples/plugins/jira/testdata/adf.json b/examples/plugins/jira/testdata/adf.jsonnew file mode 100644index 000000000..0c0a7dc37--- /dev/null+++ b/examples/plugins/jira/testdata/adf.json@@ -0,0 +1,160 @@+{+ "type": "doc",+ "version": 1,+ "content": [+ {+ "type": "heading",+ "attrs": {+ "level": 2+ },+ "content": [+ {+ "type": "text",+ "text": "Plan"+ }+ ]+ },+ {+ "type": "bulletList",+ "content": [+ {+ "type": "listItem",+ "content": [+ {+ "type": "paragraph",+ "content": [+ {+ "type": "text",+ "text": "one"+ }+ ]+ },+ {+ "type": "orderedList",+ "content": [+ {+ "type": "listItem",+ "content": [+ {+ "type": "paragraph",+ "content": [+ {+ "type": "text",+ "text": "nested"+ }+ ]+ }+ ]+ }+ ]+ }+ ]+ },+ {+ "type": "listItem",+ "content": [+ {+ "type": "paragraph",+ "content": [+ {+ "type": "text",+ "text": "docs",+ "marks": [+ {+ "type": "link",+ "attrs": {+ "href": "https://example.com"+ }+ }+ ]+ },+ {+ "type": "text",+ "text": " by "+ },+ {+ "type": "mention",+ "attrs": {+ "text": "@Ann"+ }+ }+ ]+ }+ ]+ }+ ]+ },+ {+ "type": "codeBlock",+ "attrs": {+ "language": "go"+ },+ "content": [+ {+ "type": "text",+ "text": "x := 1"+ }+ ]+ },+ {+ "type": "table",+ "content": [+ {+ "type": "tableRow",+ "content": [+ {+ "type": "tableHeader",+ "content": [+ {+ "type": "paragraph",+ "content": [+ {+ "type": "text",+ "text": "a|b"+ }+ ]+ }+ ]+ }+ ]+ },+ {+ "type": "tableRow",+ "content": [+ {+ "type": "tableCell",+ "content": [+ {+ "type": "paragraph",+ "content": [+ {+ "type": "text",+ "text": "1"+ }+ ]+ }+ ]+ }+ ]+ }+ ]+ },+ {+ "type": "mediaSingle",+ "content": [+ {+ "type": "media"+ }+ ]+ },+ {+ "type": "someFutureNode",+ "content": [+ {+ "type": "text",+ "text": "kept"+ }+ ]+ }+ ]+}diff --git a/pluginsdk/README.md b/pluginsdk/README.mdindex d4a9878eb..8117131d6 100644--- a/pluginsdk/README.md+++ b/pluginsdk/README.md@@ -279,6 +279,8 @@ Complete plugins with their `package.sh`:- `examples/plugins/notebooks`: a parser written in Python.- `examples/plugins/links`: pages (toolbox, settings, knowledge base tab), in Python.- `examples/plugins/activity`: events, a webhook and a page, in Python.+- `examples/plugins/jira`: a Jira Cloud connector with an OAuth field, dynamic+ options, incremental sync with deletions, and a skill.## Testingdiff --git a/website-docs/03-features/25-plugins.md b/website-docs/03-features/25-plugins.mdindex c2b312eb3..6740aa96b 100644--- a/website-docs/03-features/25-plugins.md+++ b/website-docs/03-features/25-plugins.md@@ -156,6 +156,7 @@ Helm 设置 `pluginHost.enabled=true` 即可。使用本地存储(`STORAGE_TYP- `subtitles`:文档解析器,Go,使用 Host API;- `notebooks`:Jupyter 笔记本解析器,Python;- `links`:带三种页面的团队链接插件,Python;- - `activity`:订阅事件、接收 Webhook 的空间动态插件,Python。+ - `activity`:订阅事件、接收 Webhook 的空间动态插件,Python;+ - `jira`:Jira Cloud 问题同步,支持 OAuth 授权或 API 令牌,带动态选项、增量同步与问题分诊技能,Go。同一个插件既可以打包成 `host` 插件由 WeKnora 运行,也可以作为 `remote` 服务独立部署,代码不用改。